Contributing Guide

How to contribute code, documentation, tests, and failure injection scenarios to the AutonomyOps ADK.

Before You Start

  1. Read the invariants. Every change must respect Architecture → Invariants. Many violations are caught automatically by ci/scan_prohibited and ci/scan_dependencies, but some require code-review sign-off.

  2. Find the FI test. For changes to any module that has FI coverage (see FI Catalog → Matrix), verify the relevant FI test still passes.

  3. Check the package mapping. If your change adds or renames a Go package, update docs/_meta/pkg-to-page.yaml. make docs-coverage-gate will fail the PR otherwise.

Development Workflow

# 1. Fork and clone
git clone https://github.com/autonomyops/adk.git
cd adk

# 2. Build
make build

# 3. Test the affected module
cd <module>
GOWORK=off go test ./... -v -count=1

# 4. Run the CI suite locally
make lint-go
make test
make edge-fi-go      # if changing edge/
make docs-coverage-gate  # if adding/renaming packages
make docs-lint        # if changing docs

# 5. Open a PR against main

CI Gates

All of these must pass for a PR to merge:

Gate

Makefile target

Required for

Go lint

make lint-go

All code changes

Unit tests

make test

All code changes

Docs build strict

make docs-lint

All changes (docs + code)

Docs coverage gate

make docs-coverage-gate

New/renamed Go packages

Docs freshness

make docs-freshness

Renamed or deleted doc pages

Prohibited symbol scan

make edge-guardrails

Changes to edge/

Dependency graph check

make edge-scan-deps

Changes to edge/ or its deps

Edge FI Go tests

make edge-fi-go

Changes to edge/

Edge FI shell tests

make edge-fi-shell

Changes to edge/ (root-only tests skip)

Security check

make security-check

All code changes

PR Requirements

  • New exported Go package → add an entry to docs/_meta/pkg-to-page.yaml. Run scripts/docgen/seed-pkg-map.sh for a draft, then hand-edit.

  • New/changed invariant enforcement point → update Traceability → Invariant Map.

  • Change to edge/ failure mode → include or update the corresponding FI test.

  • Doc-only PR → make docs-lint and make docs-freshness must pass.

  • New doc page → add a {toctree} entry in the appropriate docs/<section>/index.md.

Adding a New Go Module

  1. Create <module>/go.mod with go 1.N (2-part, no patch version). Do not add a toolchain directive to individual go.mod files — the workspace-level toolchain go1.25.9 in go.work is authoritative for the whole repo.

  2. Add replace directives in any go.mod that imports it.

  3. Add the module to go.work use directives.

  4. If cmd/autonomy imports it, add a replace in cmd/autonomy/go.mod too.

  5. Create <module>/docs/_meta/pkg-to-page.yaml for the new module.

  6. Add the module’s test command to the CI workflow if needed.

Commit Message Style

<type>(<scope>): <short summary (≤72 chars)>

<body: why the change was needed; what invariant it affects if any>

Types: feat, fix, docs, test, refactor, chore

Examples:

feat(runtime): add release poll loop with lifecycle telemetry
fix(policy): fall back to LKG when bundle hash mismatch on load
docs(architecture): fill in invariants starter page
test(edge): add FI-C3-02 cert revocation scenario

Code Style

# Format all Go code
gofmt -w .
go vet ./...

# Check Markdown (linted in CI by markdownlint-cli2)
npx markdownlint-cli2 --config .markdownlint.yml "docs/**/*.md"

Key style rules:

  • Go: gofmt with no exceptions; standard go vet must pass

  • Markdown: max 200 chars/line (code blocks and tables exempt); fenced code blocks only

Install repo-managed Git hooks before your first commit on a clone:

make install-hooks

The pre-commit hook automatically regenerates and stages docs/_generated/ when staged changes can affect repo scan, config/test inventory, workflows, or docs coverage inputs.

Do Not Do

  • ❌ Do NOT skip ci/scan_prohibited or ci/scan_dependencies — they enforce structural invariants

  • ❌ Do NOT add a new package without updating pkg-to-page.yaml — CI will fail the PR

  • ❌ Do NOT commit with --no-verify — pre-commit hooks run important lint/invariant checks

  • ❌ Do NOT amend already-published commits — create a new commit instead

Getting Help

See Also