Xlorep DarkHelm
9b742a5a6d
## Summary This PR tightens repository quality enforcement around markdown and documentation. It adds `markdownlint` to the `cicd-checks` workflow, expands pre-commit coverage so markdown files are checked repo-wide, and cleans up the PP-58 documentation set to keep it aligned with the new policy. ## What changed - Added a `Markdownlint Check` entry to `.gitea/workflows/cicd-checks.yaml` - Added `markdownlint` to pre-commit and widened prettier coverage to include markdown files across the repo - Updated `README.md` to satisfy markdownlint line-length rules - Normalized the PP-58 documentation set: - `docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - `docs/adr/ADR003-deployable_runtime_image_contract.md` - `docs/DEVELOPMENT.md` - `docs/CICD_MULTI_STAGE_BUILD.md` - `docs/CICD_TROUBLESHOOTING_GUIDE.md` - `docs/SECURE_DOCKER_CICD.md` ## Validation - `pre-commit run markdownlint --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - `pre-commit run prettier --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - Workflow YAML validation returned no errors ## Notes This change does not alter application runtime behavior. It only strengthens CI and documentation quality enforcement. Co-authored-by: copilotcoder <copilotcoder@darkhelm.org> Reviewed-on: #68
143 lines
2.5 KiB
Markdown
143 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.
|