Contributing

Ground rules

Contributions accepted from invited collaborators. Every PR is held to the same bar: green CI, code standards below, reviewer approval. Green CI is necessary but not sufficient.

The authoritative source is the CONTRIBUTING.md in the repo root. This page mirrors it in the docs-site voice.

Development environment

git clone https://github.com/sebastienrousseau/rousseau-agent
cd rousseau-agent
make setup      # installs golangci-lint (v2) and govulncheck
make check      # vet + lint + race-tests + govulncheck

Every check that runs in CI is available locally through the Makefile. If a change passes make check, it will pass CI.

Commit standards

• Conventional Commits — feat:, fix:, refactor:, docs:, test:, chore:, ci:, perf:.
• Subject line ≤ 72 characters. Body explains why, not what. Reference the driving decision, issue, or incident.
• Do not amend published commits. Create a new commit; the reviewer prefers a series they can bisect.
• Sign your commits if you have signing configured. Not currently required, but recommended for release-tag commits.

Code standards

• Every exported identifier has a godoc comment beginning with the identifier name.
• No interface{} / any in exported APIs without a written justification in the doc comment.
• context.Context propagates through every I/O path. No hidden globals or ambient loggers; pass *slog.Logger explicitly.
• Errors wrap upward with fmt.Errorf("...: %w", err). Sentinel errors go in the package's errors.go. Prefer errors.Is / errors.As at call sites over string matching.
• No panics outside main and test helpers. Must* variants that panic on operator error (duplicate registration, invalid static schema) are allowed with a documented rationale.
• No fmt.Print* in library code. Use slog or a TUI model. The forbidigo linter enforces this.

Test standards

• Unit tests live next to the code: foo.go → foo_test.go.
• Table-driven tests preferred. Use require for stopping assertions, assert for non-stopping ones.
• Interface-based test injection over global patching. Every transport package defines a narrow interface (WSConn, IMAPClient, HTTPClient, Sender) that tests satisfy with fakes.
• Coverage target: 85% for pure business-logic packages; 75% overall.
• Race-safe: go test -race must pass. New concurrent code needs a race test if it introduces non-trivial synchronisation.
• Fuzz functions for every parser (FuzzParseFoo next to parseFoo). make fuzz runs the corpus.

See Testing for the injection pattern.

Pull request process

1. Open the PR against main. Rebase (do not merge) if main moves under you.
2. Every PR requires:
   • A rationale in the description (2–3 sentences linking to the underlying decision).
   • Green CI: vet, lint, test-race on Linux + macOS, govulncheck, codeql, reproducible-build, coverage floor.
   • Reviewer approval.
3. Squash merges only. The merge commit message is the final commit message and lands on main as one atomic change.
4. If the PR adds a new dependency, note the justification in the description. Prefer standard library over adding a dependency; prefer an existing dependency over adding a new one.

Reviewer checklist

Reviewers verify, in order:

1. Necessity. Is the change required, or does it add abstraction / feature surface without a driving requirement?
2. Scope. Does the change stay within its stated purpose, or does it bundle unrelated cleanups?
3. Boundary integrity. Does the change respect the agent → concrete dependency direction? See Architecture.
4. Test coverage. Are new code paths covered? Are edge cases exercised?
5. Error handling. Are errors wrapped with context? Are cleanup paths honest (_ = with a //nolint:errcheck justification, not silently swallowed)?
6. Godoc + linter clean. Every exported symbol documented; lint output is 0 issues.
7. Security. Does the change touch the bash tool, approval policy, transport auth, or container posture? If yes, does the PR description flag it?

Documentation contributions

Documentation lives in a separate repository. When a code PR touches user-visible surface (a new flag, a new field, a new tool), the same PR — or an immediate follow-up PR to the docs repo — must update the affected pages.

• CLI change → User Guide: CLI and Reference: CLI Commands.
• Config change → Configuration and Reference: Config Schema.
• New tool → User Guide: Tools.
• New transport → content/transports/<name>.md.
• New provider → content/providers/<name>.md.
• Behavioural change → Changelog.

Release process

Releases are cut from main:

1. Update changelog entries.
2. Tag as vX.Y.Z on the release commit.
3. The release workflow builds via GoReleaser, generates a CycloneDX SBOM, publishes a cosign signature of the checksums, and generates SLSA-3 provenance.
4. Consumers verify per the recipe in Security and Installation.

Rousseau follows Semantic Versioning: patch fixes bugs, minor adds features non-breakingly, major breaks — always with a migration recipe.

Governance

rousseau-agent is a single-maintainer project. Decision authority rests with the maintainer of record listed in go.mod and LICENSE. Contributors propose direction changes via PR discussion or by email to sebastian.rousseau@gmail.com.

Security disclosures

Do not open a public issue for a security report. Email sebastian.rousseau@gmail.com per the Security policy. Acknowledgment within 72 hours.

Next

• Architecture — the map before you change it.
• Testing — the pattern the reviewer expects.
• Security — the disclosure path.