Contributing documentation
July 13, 2026 · View on GitHub
This folder holds the how-to knowledge for contributing to Radius. The documents below are the conventions and authoring guides for the Agent Ex system — the shared knowledge base that humans read directly and every supported AI agent (GitHub Copilot in VS Code, Copilot CLI, Copilot Cloud Agent, and Claude Code) reads through a single entry point. See specs/002-agent-ex/agent-ex-plan.md for the full plan.
Agent Ex conventions and authoring guides
- contributing-agent-assets.md — the conventions reference: file-strategy rule, file-size budgets, CI gates, naming conventions, and a template for each agent asset type.
- authoring-contributing-docs.md — the standard formats for contributing and architecture docs, with one annotated example of each.
- extending-agent-ex.md — the "add a capability" decision tree, the live files to update, and the repo-onboarding checklist.
Documentation index
Every contributing doc, grouped by topic. This is the single index that AGENTS.md and CONTRIBUTING.md point to — it replaces the older competing link lists.
Authoring docs & Agent Ex
- contributing-agent-assets.md — conventions reference for every agent asset type.
- authoring-contributing-docs.md — the standard contributing/architecture doc formats.
- extending-agent-ex.md — the "add a capability" decision tree and repo-onboarding checklist.
Getting started
- Prerequisites / dev environment — install every tool and bootstrap the repo.
- First commit walkthrough — a guided, end-to-end tutorial for your first change.
- Working with forks — fork setup and staying in sync with upstream.
- Code organization — how the repository tree is laid out.
- Writing Go code — Radius Go conventions.
Building & running locally
- Building the repo —
make build,make generate, and related targets. - Running & debugging the control plane locally — run the Radius OS processes and attach a debugger.
- Running the control plane — control-plane run overview.
- Generating & installing a custom build
- Control-plane configuration & settings — config schema reference.
- Control-plane logging
- Troubleshooting installation
Testing
- Test matrix overview — every test tier and its command.
- Running functional tests
- Local test iteration
- Writing functional tests
- Test naming conventions
- Test logging
- Pushing test images to GHCR
Schema & API
CLI
CI, containers & build automation
- GitHub Actions workflows
- Dockerfiles
- Bicep files
- Shell scripts & Makefiles
- Setting up a Radius deploy environment
Pull requests & code review
Process & reference
Capability index
Maps each capability in agent-ex-features.md that this repository owns to its single primary backing doc. Capabilities added after the original Agent Ex plan use n/a. Capabilities owned by satellite repos (1.9 resource types, 1.10 dashboard, 1.13 AWS Bicep types) are out of scope here. Parent rows link to the documentation index above rather than a single doc.
| Capability | Primary backing doc |
|---|---|
| 1 Build and test | Documentation index |
| 1.1 Set up a dev environment | contributing-code-prerequisites/README.md |
| 1.2 Write Go code | contributing-code-writing/README.md |
| 1.3 Schema changes | contributing-code-schema-changes/README.md |
| 1.4 CLI commands | contributing-code-cli/README.md |
| 1.5 GitHub workflows | contributing-code-github-workflows/README.md |
| 1.6 Dockerfiles | contributing-code-dockerfiles/README.md |
| 1.7 Bicep files | contributing-code-bicep/README.md |
| 1.8 Shell scripts & Makefiles | contributing-code-shell-and-make/README.md |
| 1.11 Documentation | authoring-contributing-docs.md |
| 1.12 Pull requests | contributing-pull-requests/README.md |
| 2 Code review | contributing-code-reviewing/README.md |
| 3 Investigate issues | contributing-issues/README.md |
| n/a Configure a deploy environment | contributing-deploy-environments.md |
| 5 Author and evolve docs and capabilities | Documentation index |
| 5.1 Author a new doc | authoring-contributing-docs.md |
| 5.2 Repair drift | extending-agent-ex.md |
| 5.3 Add a capability | extending-agent-ex.md |