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

Open Beginner friendly
  • Is something wrong?
#342 3 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@IG-ABHINAV is already working on this.

Since Nov 10, 2026.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Start by reading philanthropy/ingest/_raisers_edge.py and tests/test_raisers_edge.py, plus tests/test_read_gifts.py, and note the steps a reader PR takes. Then check CONTRIBUTING.md and docs/contributing.md for where the new section belongs, and review the comments on #312, #314 and #321. Done means a linked section in CONTRIBUTING.md covering each listed step, and mkdocs build --strict passing. Comment on the issue before starting.

Written by the indexing model from the issue text.

Description

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.

Dominant language
Python
Stars
11
Forks
23
Avg merge
15h 13m
Merged PRs (30d)
30

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PhilanthroPy-Project/PhilanthroPy

All issues in PhilanthroPy-Project/PhilanthroPy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.