04 — Contribution Plan

Branch and PR workflow for the Philly build, analogous to KX's NYC contribution plan in docs/design/04_contribution_plan.md.

0. Repo facts that shape the workflow

• Default branch is main (NYC build) on mwg1378/nyc-edu-data.
• main is not branch-protected; "no direct commits to main" is convention-enforced.
• Pre-push gate: vitest run tests/unit/. Python work is gated by make test and make verify, manual until CI lands.
• The Philly build lives under a philly/ branch prefix until decision O.1 (same repo vs new repo) is settled.

1. Sync first (before every branch)

cd nyc-edu-data
git checkout main && git pull --ff-only
gh pr list --state open
git branch -r | grep philly

2. Branch per capability — philly/<p-item>

One branch + one focused PR per P-item from 03_integration_plan.md:

If a branch grows, split it (philly/source-ingest-tests-pde then philly/source-ingest-tests-opendata) — single-purpose PRs per KX's convention.

3. Additive + reviewable

Same rules as KX's NYC build:

• Every Philly change is additive to the repo. If decision O.1 lands as "same repo," NYC code is touched only behind a city flag and only when parameterization is required (e.g. getOutliers({ city: "philly" | "nyc" })). If decision O.1 lands as "new repo," NYC code is untouched entirely.
• Each PR links the gap analysis — reference the specific dimension in 02_gap_analysis.md and the P-item in 03_integration_plan.md it implements.
• PR description template: what P-item it ships · what's new vs. lifted-from-NYC · how to run it (especially Python) · what stayed unchanged · screenshots / flip-diff / QA report links.

4. House style + Python lane

• TypeScript code under scripts/loaders/philly/ (same-repo) or scripts/loaders/ (fork), matching the existing NYC idiom. Strict TS, eslint clean.
• Python pipeline mirrors KX's: requirements.txt pinned to the NYC versions; pytest golden + unit tests; make verify-philly / make test-philly wrappers (or unprefixed in fork mode).
• Commit messages match the repo's sentence-case scope-prefixed imperative style. Example: Add PDE PSSA xlsx connector + base-case validation.

5. Cross-PR coordination with NYC build

If the Philly build needs a change to shared infrastructure (e.g. extend verify/sources.yaml schema to support a new socrata field), that change ships as a separate NYC-facing PR first, reviewed by KX. Only after it merges does the Philly PR depending on it open. No piggy-backing.

This rule covers:

• pipeline/analysis/engine.py — never modified by a Philly PR unless the modification benefits NYC equally. Spec compliance is co-owned.
• verify/ infrastructure (download.py, connectors/) — likewise.
• lib/queries/schools.ts — same. If the Philly schema needs a query change, do it as a separate NYC-or-shared PR.

The principle: Philly inherits, doesn't fork-and-diverge. If the Philly build wants to do something the NYC build can't, that's a signal to either generalize on NYC's side first, or revisit decision O.1.

6. Review expectations

• Every Philly PR is reviewed by mwg1378. Philly is co-owned with NYC at the methodology and design level; mwg1378 has approval rights on every branch.
• KX is review-tagged for any cross-cutting infrastructure change (the shared-infra carve-out above).

7. Hygiene

• No force-pushes to philly/init, philly/repo-setup, or any merged Philly branch.
• Never commit data files or secrets. Extend .gitignore for data/cities/philly/processed/, data/cities/philly/reference/, the Philly equivalents of NYC's data-ignore patterns.
• Reference CSVs of official public per-school figures (SPREE files, etc.) are fine to commit — they're the audit trail.

One-line summary

Sync → philly/<p-item> branch → additive change matching house style → PR linked to gap analysis and P-item → mwg1378 review (+ KX on shared infra) → merge. No NYC code modified unless co-owned and reviewed by KX.