13 Contributing

Contributing

This project has an unusual contributing bar: not «send a patch», but «send a fact». Below — what that means practically.

---

The one rule

A useful contribution is a fact with a reference. file:line, a reproducible command with its output, a measurement artifact. Everything else is a conversation starter.

The project was built on the principle that an unverified claim is worse than no claim (every edge in the graph carries evidence; every number in the docs carries an artifact). Contributions are held to the same standard.

What is welcome (in order of value)

1. A reproducible defect: exact command, full output, ragraf --version, OS, Python version, corpus characteristics (size, languages), and — if index-related — index_status output (revision, capability, checksum state).
2. A document diverging from the code: doc path + code file:line + what exactly disagrees. (The 2026-10 revision found 10+ such divergences — they are real contributions; see the defect register.)
3. A degradation the product did not name: the contract is «no silent degradation». If something broke quietly — that's a P1-class finding even if the underlying bug is small.
4. Measurements on your corpus: run the M1/M3-style protocol (fixed tasks, baseline before, artifacts in JSON) and share numbers — even unfavorable ones. The benchmark doctrine explicitly forbids «somebody else's percentages»; your numbers are the only ones that matter for your code.
5. Architecture discussion before large patches. The project is developed for concrete tasks; a big PR without a prior conversation will likely be redesigned. Open an issue with the problem + your proposed shape first.

What will likely be declined

• Drive-by rewrites without a measured defect behind them.
• Adding a graph query language (P4 — the decision is evidence-backed and final absent new evidence).
• Features requiring services/daemons in the base install (SQLite-files-only is a principle, not a limitation we forgot to fix).
• Patches that make answers «prettier» at the cost of limits/provenance honesty (FT-23).

Development setup

git clone https://github.com/paulmann/RAGRAF.git && cd RAGRAF
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
pip install -e .
python tests/test_lang_routing.py                # 56 checks — portable suites run standalone

Conventions (enforced by tools/Invoke-ProjectDoctrine.ps1, 14 checks):

Rule	Detail
PowerShell 7.6+ only	#Requires -Version 7.6 + -PSEdition Core; no powershell.exe, no WinPS-compat
Encodings	UTF-8 without BOM, LF in shipped files — checked across the tree
Comments carry evidence	«verified by run / measured on » with the observed fact — the codebase's signature style; keep it
Fixed dependencies	version bounds in pyproject.toml (NFR-7); upgrades are deliberate acts
No silent degradation	every fallback reports itself (capability, reason, limits)
Deterministic identifiers	content hashes only; no UUIDv4/timestamps inside IDs
Index artifacts isolated	<project>/.ragraf/ only; gitignore template provided

Run the checker before submitting:

pwsh -NoLogo -NoProfile -File tools/Invoke-ProjectDoctrine.ps1

Tests

No unified runner yet (roadmap R-T5) — each suite is a standalone script printing [OK]/[FAIL] and a final count:

python tests/test_lang_routing.py    # 56   portable
python tests/test_watch.py           # 31   portable
python tests/test_script_extract.py  # 25   portable
python tests/test_threshold.py       # 23   portable
python tests/test_ensure.py          # 17   portable
python tests/test_csharp_records.py  # 12   portable
# need extras:
python tests/test_joern_server.py    # requires the Joern layer
python tests/test_graph_algo.py      # requires torch (undeclared optional — R-PKG-1)
python tests/test_cpg_call_names.py  # requires a corpus config (copy examples/ragraf.example.yaml → config/)

New tests: synthetic fixtures only (tests/fixtures/), portable, no author corpora. A test that needs a private corpus doesn't ship.

Issue templates

Use them — they encode the «fact with reference» rule:

• Defect report: command → expected → actual → environment → index_status excerpt → attachments (transcript from ~/.ragraf/logs/).
• Doc↔code divergence: doc path/section → code file:line → which one is wrong → proposed resolution.
• Measurement report: protocol used → artifacts → interpretation → limits of the measurement.

Security reports

Do not file public issues for security problems. See SECURITY.md for the private contact path. Known open items are tracked transparently in the defect register (C-01 admin token endpoint, C-02 MCP filter, C-04 shell quoting) with roadmap IDs — the project's stance is that an honestly published known gap beats a silently patched one.

Recognition

Every accepted defect report is recorded with the reporter's handle in CHANGELOG.md under «Found by» — the project keeps provenance for contributions the same way it keeps provenance for edges.

---

Next: ROADMAP →