131 lines
2.5 KiB
Markdown
131 lines
2.5 KiB
Markdown
|
# 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.
|