Chris TonjesandClaude Opus 4.7
393631ad69
Scaffolding for the YPMS in-house build. Mirrors OWC's structure so future OWC framework code can be vendored in with minimal fiddling (milestone 0.2). Includes: - pyproject.toml — Python 3.12, FastAPI, SQLAlchemy 2.x, Alembic, Postgres, pydantic-settings, structlog, cryptography. Dev extras: pytest, ruff, mypy, bandit, pip-audit. - Dockerfile — multi-stage builder + slim runtime. - docker-compose.yml — app + Postgres (on 5433 to avoid clashing with OWC on 5432) + Adminer (on 8081). - alembic.ini + migrations/env.py + baseline 0001_baseline.py (empty by design; every future change is additive and immutable once merged). - src/ypms/main.py — FastAPI factory with /healthz and /readyz. - src/ypms/settings.py — pydantic-settings config (DB URL, JWT, column encryption key, log level, env, CORS). - src/ypms/logging.py — structlog + sanitize_for_log() for the sensitive-fields-never-in-logs rule from ARCHITECTURE.md §10.1. - src/ypms/db.py — SQLAlchemy Base, engine, session factory, get_db. - src/ypms/middleware.py — RequestIdMiddleware; X-Request-ID header echoed both ways. - src/ypms/framework/ and src/ypms/security/ — empty packages, to be populated in milestones 0.2 and 0.3-0.4. - tests/test_health.py — 3 smoke tests (healthz OK, header present, header honoured on incoming). - README.md — quickstart. - CONTRIBUTING.md — hard rules mirrored from OWC. - .github/workflows/ci.yml — lint (ruff), types (mypy), tests + 80% coverage floor, SAST (bandit), SCA (pip-audit), gitleaks. Green locally: ruff clean, mypy clean, pytest 3 passed. Advances YPMS-POAM-040 (architecture doc + Phase 0 kickoff). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
53 lines
3.3 KiB
Markdown
53 lines
3.3 KiB
Markdown
# Contributing to YPMS
|
|
|
|
Hard rules — mirrored from OWC's `CONTRIBUTING.md` because the two systems share a stack, an ownership model, and an ISSO. If a rule feels wrong for YPMS, propose an amendment in a PR to this file, don't quietly break it.
|
|
|
|
## Repository conventions
|
|
|
|
1. **Migrations are immutable once merged.** Add a new Alembic revision, never edit `0001_baseline.py` or its successors. If a schema change requires undoing an older migration, the fix is a new revision, not a rewrite. Every migration is a paper trail an auditor can walk.
|
|
|
|
2. **Don't add domain logic to `src/ypms/framework/` or `src/ypms/security/`.** Those are reused by every entity; entity-specific code belongs in `src/ypms/<entity>/`. If a framework enhancement is genuinely needed, propose it in its own PR with a written reason.
|
|
|
|
3. **Every state-mutating route emits an audit row.** Enforced by `CRUDService` and the router factory once the framework lands. Don't write handlers that bypass either.
|
|
|
|
4. **501 stubs still fire RBAC + audit.** Deferred actions must route through `require_permission` and emit an audit event. Permission gaps surface at Phase 0 review, not at feature-completion.
|
|
|
|
5. **Tests required.** `src/ypms/framework/` and `src/ypms/security/` need ≥ 80% coverage. Everything else: at least one happy-path test.
|
|
|
|
6. **No `--no-verify`, `# noqa`, or `# type: ignore` without an inline comment naming the specific reason.** If you need to silence a check, say why in the code.
|
|
|
|
7. **Sensitive fields never in logs.** SSN, banking, tokens, passwords, encryption keys — route through `sanitize_for_log` before emitting or don't emit. See `src/ypms/logging.py`.
|
|
|
|
8. **No commits attributed to a person who didn't write them.** Set `user.name` and `user.email` in `git config` to yourself before committing. Co-author trailers are welcome and encouraged for pairing.
|
|
|
|
## Change control
|
|
|
|
- Every substantive change ties to a POA&M ID, a phase-plan milestone, or an issue. Include the reference in the PR description.
|
|
- `PHASE{N}_PLAN.md` is authoritative for the current phase's scope. Older plans lose to the current one on conflict.
|
|
- Cross-phase work needs a written scope-conflict note before it lands.
|
|
|
|
## Security review
|
|
|
|
- Any change touching auth, RBAC, encryption, or audit gets a second reviewer.
|
|
- Changes to `src/ypms/security/` require the ISSO's approval (currently Chris Tonjes).
|
|
- Additions to the RBAC seed require the same review as code changes — permissions are policy in this codebase.
|
|
|
|
## PR checklist
|
|
|
|
- [ ] Tests pass locally (`pytest`).
|
|
- [ ] Coverage doesn't drop below 80% on `framework/` or `security/`.
|
|
- [ ] `ruff check`, `mypy` clean.
|
|
- [ ] SAST (`bandit`) and SCA (`pip-audit`) clean, or documented waivers.
|
|
- [ ] Migration added (if schema changed); no edits to older migrations.
|
|
- [ ] Any new endpoint has RBAC + audit + a test.
|
|
- [ ] Any new sensitive field routes through the app-layer encryption helpers.
|
|
- [ ] `docs/nist-mapping.md` updated if the change wires a new NIST control.
|
|
- [ ] POA&M item updated if the change closes or advances one.
|
|
- [ ] Commit message names the phase milestone or POA&M ID it advances.
|
|
|
|
## Merging
|
|
|
|
- Squash-merge is the default. Merge commit messages should read like release notes for that PR.
|
|
- Force-pushes to `main` are not allowed. Force-pushes to feature branches during review are fine.
|
|
- CI must be green.
|