diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..68b8ace --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# Contributing to plex-playlist + +## Branch Naming Strategy + +Use the following pattern for branch names: + +``` +[type]/PP-[number]-brief-description +``` + +### Pattern Components + +- **type**: Feature category + - `feat/` – New feature + - `bug/` – Bug fix + - `docs/` – Documentation + - `refactor/` – Code restructuring + - `chore/` – Maintenance, dependencies, tooling + - `test/` – Test additions or fixes + - `perf/` – Performance improvements + +- **PP-[number]**: Issue tracker prefix + issue number + - Example: `PP-10`, `PP-15`, `PP-8` + +- **brief-description**: Kebab-case, lowercase, concise + - Example: `upgrade-backend-runtime`, `fix-startup-crash` + +### Examples + +``` +feat/PP-10-upgrade-backend-runtime +bug/PP-15-fix-startup-crash +docs/PP-8-add-api-endpoints +refactor/PP-12-extract-compatibility-checks +chore/PP-7-update-dependencies +``` + +### Useful Git Commands + +List all feature branches for this project: +```sh +git branch -l 'feat/PP-*' +``` + +List all branches for a specific issue: +```sh +git branch -l '*/PP-10-*' +``` + +## Pull Request Conventions + +### Title Format + +Keep PR titles human-friendly and descriptive: +``` +Upgrade backend to Python 3.14 with exact dependency pinning +``` + +Or if you prefer structured titles: +``` +[feat] PP-10: Upgrade backend to Python 3.14 with exact dependency pinning +``` + +### PR Description + +Include the issue reference so Gitea can auto-link: +```markdown +Fixes PP-10 + +## Summary +Brief description of changes. + +## Changes +- Bullet 1 +- Bullet 2 + +## Testing +How to verify this PR works. +``` + +## Commit Message Style + +Commits use standard Git convention with optional type prefix: + +``` +[type] Brief description (50 chars max) + +Optional longer body with more context. +Wrap at 72 characters. + +Fixes PP-10 +``` + +Example: +``` +feat: Add startup compatibility validation + +Implement runtime policy checks to fail fast if Python version +or pinned package versions don't match deployment baseline. + +Fixes PP-10 +``` + +## Code Quality Gates + +All commits must pass local pre-commit hooks: +- `ruff` (format + lint) +- `pyright` (type checking) +- `pytest` (tests + coverage ≥95%) +- `pydoclint` (docstring validation) +- `xdoctest` (doctest extraction) + +Run locally before pushing: +```sh +cd backend +uv run pytest +``` + +## Development Environment + +See [README.md](README.md#manual-setup-if-not-using-docker) for manual setup. + +For Docker development: +```sh +docker compose -f compose.dev.yml up +``` + +## Questions or Issues? + +Refer to project documentation in `docs/` or open an issue on Gitea.