chris.tonjes/YPMS
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
393631ad6908866a3c8576199fc7d7a2adc46b27
YPMS/CONTRIBUTING.md
T
Chris TonjesandClaude Opus 4.7 393631ad69 Phase 0 milestone 0.1: repo scaffold + Docker Compose 
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>
2026-09-30 16:15:45 -04:00

3.3 KiB
Raw Blame History

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.
Reference in new issue View Git Blame Copy Permalink