Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
52 lines (36 loc) · 2.61 KB

CONTRIBUTING.md

File metadata and controls

52 lines (36 loc) · 2.61 KB
Raw

Contributing to contextrot

Thanks for considering a contribution. This project is deliberately structured so the highest-impact contribution is also the easiest one.

The paved path: write an adapter

contextrot supports any agent CLI whose transcripts can be parsed into the normalized session model. Each adapter is one self-contained file — no changes to analysis or reporting code needed.

  1. Copy src/contextrot/adapters/claude_code.py as a starting point.
  2. Implement the two methods of SessionAdapter:
    • discover() — find transcript files on disk
    • parse(path) — convert one file into a Session of Steps and ToolCalls
  3. Register it in src/contextrot/adapters/__init__.py.
  4. Add a small sanitized fixture transcript under tests/fixtures/ and a test file modeled on tests/test_adapter_claude_code.py.

Adapter ground rules:

  • Tolerant parsing. Skip malformed lines, ignore unknown fields, never crash on a weird file. A partial session beats an exception.
  • No network calls. contextrot is local-only; adapters read files, period.
  • Sanitize fixtures. Strip real file paths, code, and personal data from any transcript you commit.

Wanted adapters: Codex CLI, OpenCode, Gemini CLI, OpenClaw, Cursor CLI, OpenTelemetry GenAI spans.

Other contributions

  • New outcome signals (src/contextrot/signals/): each signal must be independently testable, documented in docs/methodology.md, and reported separately in output. Open an issue first to discuss the heuristic.
  • Prescription rules (src/contextrot/analysis/prescriptions.py): must be quantified from the user's own data, with an explicit evidence threshold.
  • Bug reports: include your contextrot version, agent CLI version, OS, and — if it's a parsing bug — a sanitized snippet of the offending transcript line.

Development setup

git clone https://github.com/Priyanshu-byte-coder/contextrot
cd contextrot
pip install -e ".[dev]"
pytest
ruff check src tests
mypy src

All three must pass in CI. Python 3.9–3.13 supported (CI tests the full matrix across Linux/macOS/Windows).

Style

  • Match the existing code: type hints everywhere, docstrings explain why and document format assumptions.
  • Conventional commits (feat:, fix:, docs:, test:, chore:).
  • Keep dependencies minimal — new runtime deps need a strong justification (install speed is a feature).

Statistical honesty

This tool's credibility rests on not overclaiming. Reports must always carry n-counts, confidence intervals, and the observational-diagnostic caveat. PRs that trade rigor for a scarier headline will be declined.