plex-playlist/CONTRIBUTING.md

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:

git branch -l 'feat/PP-*'

List all branches for a specific issue:

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:

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:

cd backend
uv run pytest

Development Environment

See README.md for manual setup.

For Docker development:

docker compose -f compose.dev.yml up

Questions or Issues?

Refer to project documentation in docs/ or open an issue on Gitea.