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:

```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.