## Description Documents safe patterns for agent/script-authored PR and issue comments, so replies like `System.Collections.Hashtable` (seen on #4726) don't ship unnoticed. Adds a "Posting PR/issue comments from scripts or agents" section to `CONTRIBUTING.md` with shell-agnostic rules: file-based bodies and a read-back requirement. Refs #4757. Only the documentation checkbox of the issue is covered here, so this does not close it; the issue's decision record is below. ## Type of Change - [x] Documentation update ## Changes Made - `CONTRIBUTING.md`: new shell-neutral section: single-string file-based bodies, no collections in `-f`/`-F`, read-back verification, delete-and-repost for bad comments. **Decision on the optional follow-ups (acceptance criterion 2):** deferred. A governance-workflow regex check and a `gh-reply` helper script would add new CI/script surface to maintain for a one-off failure mode. The documented read-back step is the main guardrail. Happy to follow up if maintainers want either. ## Testing - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text Docs-only change; no code touched. Reviewed the rendered Markdown diff. ``` ## Real Behavior Proof - Environment: any OS/shell with `gh` - Steps: reviewed `git diff origin/main -- CONTRIBUTING.md`; confirmed the section renders before "Development setup" and contains no shell-specific syntax. - Not tested: not executed against a live PR (docs only). ## Runtime Rollout Safety - Rollout-managed feature(s): N/A (docs only) - Minimum rollout channel: N/A - Stable/default behavior changed: No - Kill switch / disable path: N/A - Unsafe override required: No - Qualification impact: None - Rollback path: revert the commit ## Review Readiness - [x] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [x] I have made corresponding changes to the documentation - [x] I did **not** edit `CHANGELOG.md` --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
8.0 KiB
Contributing to Headroom
Thanks for contributing! Please skim this before opening a PR : the policies exist because we've been burned skipping them, not because we love paperwork.
By participating, you agree to our Code of Conduct.
Where does my contribution go?
| Type | What to do |
|---|---|
| 🐛 Bug or small fix | Open a PR (with repro + test) |
| ✨ New feature / architectural change | Open an issue or ask in Discord first. |
| 🧹 Refactor-only | Don't. Only if a maintainer asked, as part of a concrete fix. |
🧪 Test/CI-only PR chasing a known main failure |
Don't. We're tracking it. |
| 📦 New dep or version bump | PR with written justification. |
| ❓ Question | Ask in Discord #help |
Open PR cap: 10 per author. Get existing ones merged before opening more.
Guiding principles
- Verification is the author's job, not the reviewer's.
- Supply chain is a real threat. Dependency changes get human review, every time.
Bug fixes
Every bug-fix PR must include:
- A reproduction — minimal code, failing test, or steps.
- A test that fails before your fix and passes after (unit, integration, or e2e).
If you genuinely can't write a test, say so explicitly and explain how you verified.
"Real behavior proof" — required on every external PR
We can't merge what we can't verify. Include a Real behavior proof section in the PR body covering:
- Setup you tested on (OS, Python, config, provider/model)
- Exact command or steps you ran after the patch
- After-fix evidence + observed result
- What you did not test
✅ Counts: screenshots, recordings, terminal output, copied live output, linked artifacts, redacted runtime logs. ❌ Does not count alone: unit tests, mocks, snapshots, lint, typechecks, green CI. Have them too — but they prove the test passes, not that the feature works.
PRs missing this may be autoclosed.
New features
Before writing code:
- Open a feature-request issue (or raise in Discord).
- Get a 👍 from a core maintainer before implementing.
- Include a short spec covering:
- API surface (public functions, config, CLI flags)
- Changes to existing behavior
- User stories — Given / When / Then, golden path + one edge case
- Failure modes
- Recovery / resilience
- Security considerations
Short and concrete beats long.
Dependencies & supply chain
A human maintainer reviews every dep change. PRs that add or bump a package must justify:
- Why this package (vs. doing it ourselves / using existing deps)
- Who maintains it (activity, release cadence, security history)
- Install surface (transitive deps, native code, install/runtime network)
- Why this version — permitted reasons: bug fix, security patch, required new functionality. Cosmetic bumps will be closed.
PR workflow
- Fork, branch from
main. - Install Node 18+ and run
uv sync --extra devthenmake install-git-hooks— installs repo pre-commit checks on every commit, commitlint on every commit message, and ci-precheck on every push. - One logical change per PR.
- Add tests.
uv run pytest·uv run ruff check .·uv run ruff format .- Do not edit
CHANGELOG.md— release-please generates it from your Conventional Commit PR title, so a clearfix(...)/feat(...)title is your changelog entry. A CI guard rejects manual edits. - Open the PR with a clear description +
Real behavior proof+ any spec/justification required, and keep the PR in draft until theReview Readinessboxes are complete.
Title format (conventional commits): feat:, fix:, docs:, test:, refactor:.
Commit message format is enforced locally by the repo's commit-msg hook and again in CI.
Review: CI green, one maintainer review, coverage held/improved.
Posting PR/issue comments from scripts or agents
A successful API call (exit 0) only proves a comment was created, not that its body is right. Scripts must:
- Pass the body as a single plain string via a file (
gh pr comment --body-file,gh issue comment --body-file, orgh api --input <json-file>). Avoid inline multi-line strings, which differ across shells, and never pass a collection or object as a field value (-f body=...). - Re-fetch the posted comment and confirm the body reads as intended before reporting success.
- If the body is a bare type name (e.g.
System.Collections.Hashtable) or otherwise garbled, delete it and repost:gh api -X DELETE repos/<owner>/<repo>/pulls/comments/<id>for review comments,.../issues/comments/<id>for issue and top-level PR comments.
Development setup
git clone https://github.com/headroomlabs-ai/headroom.git
cd headroom
python -m venv .venv && source .venv/bin/activate
node --version # Node 18+ required for commitlint hooks
python -m pip install --upgrade pip
python -m pip install -e ".[dev,relevance,proxy]"
python -m pytest
Headroom uses a pyproject.toml/maturin build backend. Older pip
versions may fail editable installs by looking for setup.py; upgrade pip
first or use uv sync --extra dev.
Handler tests that read request bodies should use a real Starlette Request
with ASGI receive messages, including streamed chunks, rather than patching the
body reader. Size-limit regressions must configure an explicit test ceiling;
the production ceiling is independent of the compression admission threshold.
Avoid replacing imported proxy packages in sys.modules: it can split live
helper and exception identities across full-suite test orderings.
Dev Containers
Two configs ship for VS Code / Codespaces:
.devcontainer/devcontainer.json— Python 3.12,uv, Node.js,gh..devcontainer/memory-stack/devcontainer.json— adds Qdrant + Neo4j sidecars (useqdrant:6333,neo4j://neo4j:7687).
Inside, use: uv run ruff check ., uv run pytest, etc.
Optional automated review
This repository includes .github/copilot-instructions.md so maintainers can opt into GitHub Copilot code review without adding workflow billing noise to every PR.
Enable or disable automatic Copilot review in Settings → Rules → Rulesets → Automatically request Copilot code review. Keep it off unless maintainers explicitly want the extra review traffic.
Coding standards
- Ruff for lint + format, line length 100, PEP 8.
- Type hints on public functions; Google-style docstrings.
- Cover new behavior + edge cases; aim >80% coverage on new code.
- Python 3.11+. Optional features go behind extras.
- For an optional-integration change, run its owner tests and
mypy headroomwith the relevant extra installed. A hook environment without that dependency does not check the imported library's types. CI lint installslangchain-corefor its normal mypy run; keep typechecking there rather than launching a second mypy subprocess from pytest. - Headroom writes LF and normalizes on read, on every platform. Pass
newline="\n"to everywrite_text/openthat writes a context, memory, or state file, and normalize\r\n/\rwhen you read one back. Without the pin,TextIOWrappertranslates\nto\r\non Windows, and a reader that decodes bytes directly then re-writes accumulates carriage returns (#3594); even with a normalizing reader, two subsystems writing the same file (CLAUDE.md,AGENTS.md) flip it between LF and CRLF (#3698). Cover new write sites with@pytest.mark.windows_newline— those tests assert thenewline=kwarg (an artifact assertion cannot fail on POSIX) and also run onwindows-latestin CI.
Architecture principles
Safety first: never drop user/assistant content, never break tool call/response pairing, malformed content passes through unchanged, prefer false negatives.
Performance: transforms <50ms at P99, lazy-load optional deps, profile before optimizing.
Contributors are credited in CHANGELOG, the GitHub contributors page, and release notes. Thanks again. 💚