Roadmap: phases, issues, and where to start

This is a roadmap index, not a code change, so start by reading CONTRIBUTING.md and the how-to-pick-up steps in the body. To find real work, open a good first issue such as #338 (CLI --source presets) or #351 (1.0 gates against main). Done here means you understand the phase order and have picked an issue, and any plan question goes in a comment on this issue.

This is the map of planned work, phase by phase. Each phase is a milestone, and every issue in it has a Goal, Acceptance criteria, Scope, Where to start, and Dependencies, so you can pick one up without asking first. Phase order is a release plan: independent work in a later phase is welcome now.

Last reviewed 2026-11-04 against main at e410de6.

How to pick something up

1. New here? Start with an issue labelled good first issue. Those need no fundraising knowledge.
2. Comment on the issue before you start, so two people don't build the same thing. If you stop, say so and it goes back up for grabs.
3. Follow CONTRIBUTING.md: editable install, make ci once before opening the PR, one CHANGELOG bullet under [Unreleased].
4. Research issues (Phase 4) follow one rule: a model or setting is adopted only if it beats its simple rule on a held-out fold. A rejected result with numbers is a finished issue, not a failure.

Phase 1: CLI correctness and parity

Every CLI command counts the same gifts as the Python API and accepts every CRM preset.

• #337 check and train --task leadership count pledges and cancelled gifts (merged in 03c3c43)
• #338 CLI --source accepts only 4 of 7 presets (PR #354, review points open)
• #341 check and train --task leadership accept every read_gifts source (PR #359; merge after #354, both edit the --source choices)
• #340 Test on Python 3.14 (good first issue)

Phase 2: CRM coverage

Readers for the remaining CRMs, checked against each vendor's own docs.

Merge order matters here: each new reader adds a GIFT_SOURCES name, and once #341 lands a test requires every name to have a CLI raw-gift entry. Whichever of a reader PR and #359 lands second adds the missing entry. The reader issues spell this out.

• #342 "How to add a CRM ingest reader" contributor checklist (good first issue)
• #339 README and ingest how-to miss four readers (PR #355, merge conflict to resolve)
• #360 read_gifts docstring names 5 of 7 sources (good first issue)
• #238 Little Green Light reader (PR #312, merged ebbf2df)
• #237 Neon CRM reader (PR #314: merged with main 2026-11-04; on hold until someone posts a real Neon export header, because Neon's public docs don't name the type column or its values)
• #241 Ellucian Advance reader (PR #321, merged e691817)
• #239 Virtuous reader (claimed 2026-09-30, no PR yet)

Phase 3: Trust in a score

Can a user believe the score on their own file?

• #343 How-to: calibration by decile (good first issue)
• #344 Warn when a re-scored file drifts from the training file
• #345 Plot one donor's score explanation
• #5 Optional SHAP extra (on hold; see the latest comment there)

Phase 4: Back-tested candidate models

• #346 Second-gift conversion on DonorsChoose
• #347 Next-gift timing (within 90 days)
• #348 Tune UpliftTLearner and report Qini
• #349 Tune the leadership model's inner classifier
• #350 FinancialForecastModel on a real revenue series

Phase 5: Toward 1.0

• #351 Re-check the 1.0 gates against main (report posted 2026-11-03; done once #357 lands)
• #357 Gate 2 fails on wording: ratify the three post-0.7.0 exemptions and reword the gate (good first issue)
• #361 Document the latest-discharge keying limitation (good first issue)
• #366 macOS test job cancelled at ~15 minutes with no logs (turns main red; blocks merges until re-run)
• #110 GratefulPatientFeaturizer encounter keying: design decision. Not a 1.0 blocker once #361 lands, because the classes are Tier 2 and may change in a 1.x minor

Phase 6: Community and JOSS

• #127 JOSS submission tracking (target Monday 2026-12-07; merge freeze from 2026-11-30)
• #126 Who's using this? thread (posted as #158, not pinned; 2 of 3 external issues, 1 of 2 Discussion replies)
• #83 One named institutional user

Repo hygiene, one PR (#367, merged 2026-11-04; before the JOSS date, since a reviewer reads the README and the Community tab first):

• #362 README says 1.0.0 is merged; bug form suggests 0.7.0 (good first issue)
• #363 CLI quick start and a recorded demo right after Installation
• #364 ADOPTERS.md and an "I use PhilanthroPy" issue form
• #365 Community tab reports no issue template (YAML forms aren't counted)

This issue is updated as phases move. Questions about the plan itself go here; questions about one task go on that task's issue.