mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## 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>
163 lines
8.0 KiB
Markdown
163 lines
8.0 KiB
Markdown
# 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](CODE_OF_CONDUCT.md).
|
|
|
|
## 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:
|
|
|
|
1. **A reproduction** — minimal code, failing test, or steps.
|
|
2. **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:
|
|
|
|
1. **Open a feature-request issue** (or raise in Discord).
|
|
2. **Get a 👍 from a core maintainer** before implementing.
|
|
3. **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
|
|
|
|
1. Fork, branch from `main`.
|
|
2. Install **Node 18+** and run `uv sync --extra dev` then `make install-git-hooks` — installs repo pre-commit checks on every commit, commitlint on every commit message, and ci-precheck on every push.
|
|
3. One logical change per PR.
|
|
4. Add tests.
|
|
5. `uv run pytest` · `uv run ruff check .` · `uv run ruff format .`
|
|
6. Do **not** edit `CHANGELOG.md` — release-please generates it from your Conventional Commit PR title, so a clear `fix(...)`/`feat(...)` title *is* your changelog entry. A CI guard rejects manual edits.
|
|
7. Open the PR with a clear description + `Real behavior proof` + any spec/justification required, and keep the PR in draft until the `Review Readiness` boxes 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`, or `gh 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
|
|
|
|
```bash
|
|
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 (use `qdrant: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](https://github.com/astral-sh/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 headroom`
|
|
with the relevant extra installed. A hook environment without that dependency
|
|
does not check the imported library's types.
|
|
CI lint installs `langchain-core` for 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 every `write_text`/`open` that writes a context, memory,
|
|
or state file, and normalize `\r\n`/`\r` when you read one back. Without
|
|
the pin, `TextIOWrapper` translates `\n` to `\r\n` on 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 the
|
|
`newline=` kwarg (an artifact assertion cannot fail on POSIX) and also run
|
|
on `windows-latest` in 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. 💚
|