# 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)

```bash
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`:

| Order | Branch | Maps to | Scope |
|---|---|---|---|
| init | `philly/init` | P-init | this folder — design docs + scaffolding stubs; **the current branch** |
| 0 | `philly/repo-setup` | P0 | Decision O.1 implementation: either same-repo namespace or new-repo fork |
| 1 | `philly/source-ingest-tests` | P1 | PDE + OpenDataPhilly + Future Ready PA Index connectors for test/grad/absenteeism |
| 2 | `philly/source-ingest-survey` | P2 | PSES Zip ingest + survey rollups |
| 3 | `philly/derive-peer-groups` | P3 | KNN peer-group derivation + percentile compute on Philly data |
| 4 | `philly/validation` | P4 | (i)–(iii) checks per metric; SPREE as spot-check reference |
| 5 | `philly/site-and-stories` | P5 | UI adaptation + 25 story stubs + recipes |

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.