Thanks for your interest! This guide covers the conventions used across the GrayCodeAI repositories. The shared standards (versioning, release tooling, repo layout) are defined in https://github.com/GrayCodeAI/reflect/blob/main/docs/versioning.md.
- Fork the repo and create a feature branch off
main:git checkout -b feat/short-description
- Make your changes in small, focused commits.
- Run the full local check before pushing:
make ci
- Open a pull request. CI will re-run the same checks plus security scanning, race-detector tests, and (where applicable) integration tests.
This repo uses the standardised GrayCodeAI Makefile targets. Run make help
for the full list. The most common targets:
| Target | What it does |
|---|---|
make build |
Build the binary / verify the library compiles |
make test |
Run unit tests |
make test-race |
Run unit tests with the race detector |
make cover |
Generate a coverage report |
make lint |
Run golangci-lint (pinned to CI's version) |
make fmt |
Format source files |
make vet |
Run go vet |
make security |
Run govulncheck |
make ci |
Run everything CI runs (the gate before pushing) |
Repo-specific dev targets:
| Target | What it does |
|---|---|
make setup |
Install local development tools; use published dependencies. |
make boundaries |
Alias for all boundary guards (matches make boundaries in engine repos). |
make test-10x |
Run tests 10 times to surface flakes. |
make smoke |
Quick build + doctor + ecosystem verification. |
Reflect builds independently with the published Relay dependency in go.mod.
For coordinated Relay changes, create an optional local overlay:
make workspace RELAY_DIR=/path/to/relay
GOWORK=off go test -modfile=go.local.mod ./...The overlay stays gitignored. Run make ci against the published dependency
before release. Setup and CI never generate a parent go.work.
We use Conventional Commits. Pull request titles and commit subjects follow it so the history reads cleanly and the release PR can group changes. There is no release bot: releases are cut by hand (see docs/RELEASING.md).
<type>(<optional scope>): <short summary>
<optional body>
<optional footer(s)>
Types:
feat:— a new featurefix:— a bug fixperf:— performance improvementrefactor:— code restructure with no behaviour changedocs:— documentation onlytest:— adding or fixing testsbuild:— build system or dependenciesci:— CI configurationchore:— anything elserevert:— reverts a previous commit
Breaking changes: add ! after the type/scope or include BREAKING CHANGE: in the footer, and call the change out in CHANGELOG.md.
Examples:
feat(client): add streaming retry with exponential backoff
fix: handle empty response body in chat handler
refactor!: rename ClientV1 to Client (BREAKING CHANGE)
Co-authors: do not add Co-authored-by: trailers. Commits should list
only the human author. Hooks are auto-installed by make setup via
lefthook. To re-install manually:
make hooksCursor / IDE commits: some editors inject Co-authored-by: Cursor via their
own git hooks. Use the clean commit helper to bypass IDE hooks while keeping
lefthook checks on normal commits:
./scripts/commit-clean.sh -m "fix(scope): your message"After a history rewrite: reset stale local SHAs with:
./scripts/sync-clone.shSigned commits are required in this repo.
- Git is configured for SSH commit signing.
- In sandboxed agent sessions,
git commitcan fail even when the signing key is unlocked because the sandbox cannot access the hostSSH_AUTH_SOCK. - When signing is required, run
git commitoutside the sandbox or through an unsandboxed/escalated execution path.
Before requesting review:
-
make cipasses locally. - New behaviour has tests; bug fixes have a regression test.
- User-visible changes have an entry under
## [Unreleased]inCHANGELOG.md(Keep a Changelog: Added / Changed / Fixed / Removed / Security). -
VERSIONis left alone — it changes only in a release PR (docs/RELEASING.md). - Public API changes have updated doc comments.
- No secrets, API keys, or PII in code, comments, tests, or fixtures.
- Reviewers focus on correctness, design, and tests; formatting is enforced by tooling, not humans.
- Authors respond to every comment (resolved, addressed, or politely declined with rationale) — no silent dismissals.
- Squash-merge by default; the PR title becomes the commit (so it must be a valid Conventional Commit message).
- One approving review from a CODEOWNERS-listed reviewer is required.
Open an issue using the bug-report template. Include the reflect
version (reflect --version for binaries, reflect.Version for
libraries — see this repo's VERSION file), reproduction steps, expected
behaviour, and actual behaviour.
Do not open a public issue. See SECURITY.md for private reporting channels.
By contributing, you agree that your contributions will be licensed under the same license as this repo (see LICENSE).