docs: "How to add a CRM ingest reader" checklist for contributors

Aperta Adatta ai principianti
  • Qualcosa non va?
#342 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
Mezza giornata
Idoneità per principianti
68/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation

Direzione di ricerca

Inizia leggendo philanthropy/ingest/_raisers_edge.py e tests/test_raisers_edge.py, oltre a tests/test_read_gifts.py, e annota i passaggi che compie una PR di un lettore. Controlla poi CONTRIBUTING.md e docs/contributing.md per capire dove va inserita la nuova sezione, e rivedi i commenti su #312, #314 e #321. Il lavoro è completo quando una sezione collegata in CONTRIBUTING.md copre ogni passaggio elencato e mkdocs build --strict termina con successo. Commenta la issue prima di iniziare.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

beginner documentation good first issue roadmap
Goal

A new contributor can add a CRM reader in one pass, without the review round-trips the last four reader PRs needed.

Acceptance criteria
  • A section in CONTRIBUTING.md (linked from docs/contributing.md) lists every step a reader PR needs, in order.
  • It covers: citing the vendor's own docs for every field name and type/status term (module docstring and PR body); header aliases onto contact_id / receive_date / total_amount; a DEFAULT_... exclusion or inclusion constant where None or an empty sequence disables the filter; a warning when the type/status column is missing; the typed empty frame; delegating to civicrm_contributions_to_features(..., statuses=None).
  • It covers registration: GIFT_SOURCES, _REGISTRY and the read_gifts docstring in _read_gifts.py, the import and alphabetical __all__ entry in ingest/__init__.py, and a row in docs/reference/index.md.
  • It covers the CLI: the private _<crm>_received_rows row-filter helper that *_to_features calls, and its entry in the CLI's raw-gift reader table (#341), which check and train --task leadership use. features --source needs nothing once #338 lands.
  • It covers tests: a tests/test_<crm>.py file, the two read_gifts tests (path matches the direct call; the filter kwarg reaches the aggregator), and the hardcoded GIFT_SOURCES set in tests/test_read_gifts.py.
  • It says to add exactly one CHANGELOG bullet and never run an editor formatter over CHANGELOG.md, and shows git diff upstream/main -- CHANGELOG.md as the check.
  • mkdocs build --strict passes.
Scope

Docs only. Take the steps from an existing reader such as philanthropy/ingest/_raisers_edge.py and its tests, not from memory.

Where to start
  • CONTRIBUTING.md, docs/contributing.md
  • philanthropy/ingest/_raisers_edge.py, tests/test_raisers_edge.py, tests/test_read_gifts.py
  • Review comments on #312, #314 and #321 for what tripped people up
Dependencies
  • None to start. Write the CLI step against #341's final shape: if PR #359 has not merged, describe the step and update it when it does.

Phase order is a release plan, not a rule against picking up independent work early. Comment on this issue before you start so two people don't build the same thing.

Lingua principale
Python
Stelle
11
Fork
23
Merge medio
2g 19h
PR unite (30g)
31

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di PhilanthroPy-Project/PhilanthroPy

Tutte le issue di PhilanthroPy-Project/PhilanthroPy

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.