Backend runtime upgraded to Python 3.14 with exact dependency pinning (#57)
Some checks failed
CICD Start / Sanity and Base Decision (push) Successful in 18s
Runner Canary / Canary Heavy (ubuntu-act-8gb) (push) Has been skipped
Runner Canary / Canary Heavy (ubuntu-act-4gb) (push) Has been skipped
Runner Canary / Canary Burst (ubuntu-act (push) Failing after 11m10s
Runner Canary / Canary (ubuntu-latest) (push) Failing after 12m39s
Runner Canary / Canary (ubuntu-act) (push) Failing after 12m42s

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>

## Summary

Upgrades backend runtime baseline and dependency management for issue #10.

### Changes

1. **Python Baseline**: Updated from 3.13 to 3.14
   - Updated `backend/pyproject.toml` requires-python constraint
   - Updated `backend/pyrightconfig.json` pythonVersion
   - Updated all Dockerfile and CI references

2. **Dependency Pinning**: Switched to exact version pins in `backend/pyproject.toml`
   - All dev and runtime dependencies now use `==` instead of `>=`
   - `fastapi==0.120.2`, `uvicorn==0.38.0`
   - ruff, pyright, pytest suite pinned to current resolved versions
   - Regenerated `backend/uv.lock` under Python 3.14

3. **Startup Compatibility Guard** (TDD via RED→GREEN)
   - New `compatibility_status()` function evaluates runtime and pinned deps
   - Startup raises `RuntimeError` if policy fails
   - Implemented via FastAPI lifespan (non-deprecated) handler

4. **Compatibility Status Endpoint**
   - New `GET /compatibility` returns policy status, runtime version, and package checks
   - Shares single source of truth with startup validation

5. **Integration Tests**
   - Added failing-then-passing tests for startup guard and endpoint behavior
   - 100% coverage maintained

6. **Direnv Configuration**
   - Added `UV_PYTHON="3.14"` pin to repo `.envrc`
   - Ensures direnv creates/recreates venv with correct Python version

### Validation

-  ruff format/check
-  pyright strict (0 errors)
-  pytest: 8 passed, 100% coverage (>=95 gate)
-  pydoclint: pass
-  xdoctest: pass

### Notes

- SQLAlchemy/SQLModel introduction deferred to next pass per scope
- Compatibility logic currently validates fastapi/uvicorn pins (runtime deps)
- Ready for container build validation and Renovate bot testing

Co-authored-by: copilotcoder <copilotcoder@darkhelm.org>
Reviewed-on: #57
Co-authored-by: Cliff Hill <xlorep@darkhelm.org>
Co-committed-by: Cliff Hill <xlorep@darkhelm.org>
This commit was merged in pull request #57.
This commit is contained in:
2026-06-18 11:19:24 -04:00
committed by Xlorep DarkHelm
parent 5d74dd8d8f
commit d02039a22e
52 changed files with 4480 additions and 966 deletions

130
CONTRIBUTING.md Normal file
View File

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