docs: Contributing guide — building and the rad CLI#12180
Merged
brooke-hamilton merged 2 commits intoJun 22, 2026
Merged
Conversation
Reformat contributing-code-building/README.md and contributing-code-cli/README.md into the standard Purpose -> Prerequisites -> Steps -> Verification -> Troubleshooting format and verify every command, path, flag, and make target against current code. Consolidate the first-commit building and CLI steps into thin walkthroughs that link to the authoritative docs instead of duplicating them, removing the sync burden and stale CLI help output. Fix stale references found during verification (WS4): - The dead running-rad-cli.md link in first-commit-03 now points to the CLI guide. - VS Code debug config corrected to the only existing one, 'Debug rad CLI (prompt for args)'; the nonexistent 'Launch rad CLI' / basic 'Debug rad CLI' references are removed. - version command path corrected to pkg/cli/cmd/version/version.go. - Update the inbound #build-the-container-images anchor in generating-and-installing-custom-build.md after the heading rename. Convert first-commit screenshots to Markdown image syntax to satisfy markdownlint MD033. Verified: cspell, markdownlint, and relative-link/anchor resolution all pass on the changed files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR (Phase 3 · PR 3) refactors the Radius contributing documentation so the “Building the code” and “Develop the Radius CLI” guides become the single authoritative references, and the first-commit walkthrough steps link to them instead of duplicating content (reducing drift across docs).
Changes:
- Rewrites the build and CLI guides into the standard Purpose → Prerequisites → Steps → Verification → Troubleshooting format and aligns examples with current repo targets/config.
- Shortens first-commit walkthrough steps (building/CLI/debugging) to one-pass instructions plus links to the authoritative guides, and converts
<img>tags to Markdown images. - Fixes a control-plane doc link anchor to match the updated build guide heading.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/contributing/contributing-code/contributing-code-building/README.md | Becomes the authoritative build guide; documents make build, verification, containers, and generation. |
| docs/contributing/contributing-code/contributing-code-cli/README.md | Becomes the authoritative CLI dev guide; covers go run, install, VS Code debug config, and CLI error-handling conventions. |
| docs/contributing/contributing-code/contributing-code-first-commit/first-commit-02-building/index.md | Walkthrough step shortened to a single build flow + link to build guide. |
| docs/contributing/contributing-code/contributing-code-first-commit/first-commit-03-working-on-cli/index.md | Walkthrough step shortened; links to CLI guide; removes stale help-text sample; uses Markdown images. |
| docs/contributing/contributing-code/contributing-code-first-commit/first-commit-04-debugging-cli/index.md | Walkthrough step shortened; aligns to the single current VS Code launch config; uses Markdown images. |
| docs/contributing/contributing-code/contributing-code-control-plane/generating-and-installing-custom-build.md | Updates link anchor to the renamed build-guide section. |
Replace the hard-coded ./dist/darwin_amd64/release/rad with the generic ./dist/<GOOS>_<GOARCH>/release/rad form so contributors on Linux/arm64 and other platforms don't try to run a non-existent binary. The path is copied from the build output anyway, and the rest of the doc already uses the generic layout. Addresses Copilot review feedback on PR #12180. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>
10 tasks
10 tasks
brooke-hamilton
changed the title
lakshmimsft
approved these changes
Jun 22, 2026
brooke-hamilton
merged commit c7c9226
into
brooke-hamilton/agentex-phase3
5 checks passed
brooke-hamilton
added a commit
that referenced
this pull request
Jul 1, 2026
## Summary This is **PR 3 (Building + CLI)** of the [Agent Ex — Phase 3 (Contributing docs) plan](https://github.com/radius-project/radius/blob/brooke-hamilton/agentex-phase3/specs/002-agent-ex/agent-ex-phase-3-plan.md) — see the **PR 3** task under §6 of that plan. The goal is to make the "build the code" and "develop the CLI" guides the one place each topic is documented, and to stop the step-by-step tutorial from repeating (and drifting from) that content. ## Merge target⚠️ This PR targets the `brooke-hamilton/agentex-phase3` **plan branch, not `main`**. It is one of seven stacked PRs for this phase; approving and merging it lands the change on the plan branch only — **it does not merge anything to `main`**. The whole phase rolls up to `main` in a single follow-up PR after all of this phase's PRs land. ## Files changed All six files are edits — nothing is added or deleted. - **`docs/contributing/contributing-code/contributing-code-building/README.md`** — rewritten into the repo's standard doc format (Purpose → Prerequisites → Steps → Verification → Troubleshooting) and made the authoritative build guide. Every `make` command in it was checked against the Makefiles in `build/`. - **`docs/contributing/contributing-code/contributing-code-cli/README.md`** — rewritten into the same standard format and made the authoritative CLI-development guide, now including the VS Code debugging walkthrough. - **`docs/contributing/contributing-code/contributing-code-first-commit/first-commit-02-building/index.md`** — shortened so it walks a newcomer through one build, then links to the building guide instead of repeating it. Also removed an out-of-date CLI help-text sample. - **`docs/contributing/contributing-code/contributing-code-first-commit/first-commit-03-working-on-cli/index.md`** — shortened to link to the CLI guide, and fixed a broken link that pointed at a page (`running-rad-cli.md`) that does not exist. - **`docs/contributing/contributing-code/contributing-code-first-commit/first-commit-04-debugging-cli/index.md`** — shortened to link to the CLI guide's debugging section. Updated it to match the one VS Code debug configuration that actually exists today. - **`docs/contributing/contributing-code/contributing-code-control-plane/generating-and-installing-custom-build.md`** — one-line link fix: updated a link anchor that pointed at a heading I renamed in the building guide. ## Other things worth knowing for review - The broken `running-rad-cli.md` link now points to `contributing-code-cli/README.md`, which already contains that content — so no new page was needed. - I corrected a couple of stale code references found while verifying: the only rad debug config in `.vscode/launch.json` is "Debug rad CLI (prompt for args)" (the docs named configs that no longer exist), and the version command lives at `pkg/cli/cmd/version/version.go`. - The first-commit screenshots are unchanged; I only converted their `<img>` tags to Markdown image syntax so the docs pass the Markdown linter. - I did not touch any of the planning documents for this work. --------- Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
nithyatsu
pushed a commit
to nithyatsu/radius
that referenced
this pull request
Jul 2, 2026
…dex layer (radius-project#12290) ## Origin Agent Ex is the effort to turn `docs/contributing/` into a single shared knowledge base that humans and every supported AI agent (Copilot in VS Code, Copilot CLI, Copilot Cloud Agent, Claude Code) read through one entry point. The [Agent Ex plan](specs/002-agent-ex/agent-ex-plan.md) splits the work into phases; this PR delivers [Phase 3 — Contributing docs](specs/002-agent-ex/agent-ex-phase-3-plan.md), whose north star is that every "how do I do X?" question has exactly one current, correctly-formatted primary doc, reachable from one index. ## Scope - **Consolidate + reformat.** The seven topic clusters (entry point, prerequisites, building + CLI, running/debugging locally, testing, schema changes, process/reference) are each collapsed into one authoritative doc in the standard **Purpose → Prerequisites → Steps → Verification → Troubleshooting** format; deprecated/duplicate docs (`how-to.md`, `running-controlplane-locally.md`) are deleted and inbound links repointed. - **Documentation index + capability index** added to `docs/contributing/README.md`, replacing the older competing link lists. - **Four new primary docs** for capabilities 1.5–1.8 (GitHub workflows, Dockerfiles, Bicep files, shell scripts & Makefiles) that the `.github/instructions/*` files complement. - **Code↔doc path map** seeded in `contributing-agent-assets.md` for the docs-drift review step. ## History This branch was built up from seven topic PRs, each consolidating and reformatting one cluster, then merged here: - radius-project#12174 — entry point and CONTRIBUTING.md - radius-project#12175 — prerequisites and dev environment - radius-project#12176 — running and debugging locally - radius-project#12177 — testing - radius-project#12178 — process and reference docs - radius-project#12179 — schema changes - radius-project#12180 — building and the rad CLI This PR adds the index layer on top (documentation index, capability index, the four new 1.5–1.8 docs, and the path map). ## Verification `cspell` and `markdownlint` clean on changed files; all relative links and anchors resolve. --------- Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
sk593
pushed a commit
that referenced
this pull request
Jul 6, 2026
…dex layer (#12290) ## Origin Agent Ex is the effort to turn `docs/contributing/` into a single shared knowledge base that humans and every supported AI agent (Copilot in VS Code, Copilot CLI, Copilot Cloud Agent, Claude Code) read through one entry point. The [Agent Ex plan](specs/002-agent-ex/agent-ex-plan.md) splits the work into phases; this PR delivers [Phase 3 — Contributing docs](specs/002-agent-ex/agent-ex-phase-3-plan.md), whose north star is that every "how do I do X?" question has exactly one current, correctly-formatted primary doc, reachable from one index. ## Scope - **Consolidate + reformat.** The seven topic clusters (entry point, prerequisites, building + CLI, running/debugging locally, testing, schema changes, process/reference) are each collapsed into one authoritative doc in the standard **Purpose → Prerequisites → Steps → Verification → Troubleshooting** format; deprecated/duplicate docs (`how-to.md`, `running-controlplane-locally.md`) are deleted and inbound links repointed. - **Documentation index + capability index** added to `docs/contributing/README.md`, replacing the older competing link lists. - **Four new primary docs** for capabilities 1.5–1.8 (GitHub workflows, Dockerfiles, Bicep files, shell scripts & Makefiles) that the `.github/instructions/*` files complement. - **Code↔doc path map** seeded in `contributing-agent-assets.md` for the docs-drift review step. ## History This branch was built up from seven topic PRs, each consolidating and reformatting one cluster, then merged here: - #12174 — entry point and CONTRIBUTING.md - #12175 — prerequisites and dev environment - #12176 — running and debugging locally - #12177 — testing - #12178 — process and reference docs - #12179 — schema changes - #12180 — building and the rad CLI This PR adds the index layer on top (documentation index, capability index, the four new 1.5–1.8 docs, and the path map). ## Verification `cspell` and `markdownlint` clean on changed files; all relative links and anchors resolve. --------- Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: sk593 <shruthikumar@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This is PR 3 (Building + CLI) of the Agent Ex — Phase 3 (Contributing docs) plan — see the PR 3 task under §6 of that plan. The goal is to make the "build the code" and "develop the CLI" guides the one place each topic is documented, and to stop the step-by-step tutorial from repeating (and drifting from) that content.
Merge target
brooke-hamilton/agentex-phase3plan branch, notmain. It is one of seven stacked PRs for this phase; approving and merging it lands the change on the plan branch only — it does not merge anything tomain. The whole phase rolls up tomainin a single follow-up PR after all of this phase's PRs land.Files changed
All six files are edits — nothing is added or deleted.
docs/contributing/contributing-code/contributing-code-building/README.md— rewritten into the repo's standard doc format (Purpose → Prerequisites → Steps → Verification → Troubleshooting) and made the authoritative build guide. Everymakecommand in it was checked against the Makefiles inbuild/.docs/contributing/contributing-code/contributing-code-cli/README.md— rewritten into the same standard format and made the authoritative CLI-development guide, now including the VS Code debugging walkthrough.docs/contributing/contributing-code/contributing-code-first-commit/first-commit-02-building/index.md— shortened so it walks a newcomer through one build, then links to the building guide instead of repeating it. Also removed an out-of-date CLI help-text sample.docs/contributing/contributing-code/contributing-code-first-commit/first-commit-03-working-on-cli/index.md— shortened to link to the CLI guide, and fixed a broken link that pointed at a page (running-rad-cli.md) that does not exist.docs/contributing/contributing-code/contributing-code-first-commit/first-commit-04-debugging-cli/index.md— shortened to link to the CLI guide's debugging section. Updated it to match the one VS Code debug configuration that actually exists today.docs/contributing/contributing-code/contributing-code-control-plane/generating-and-installing-custom-build.md— one-line link fix: updated a link anchor that pointed at a heading I renamed in the building guide.Other things worth knowing for review
running-rad-cli.mdlink now points tocontributing-code-cli/README.md, which already contains that content — so no new page was needed..vscode/launch.jsonis "Debug rad CLI (prompt for args)" (the docs named configs that no longer exist), and the version command lives atpkg/cli/cmd/version/version.go.<img>tags to Markdown image syntax so the docs pass the Markdown linter.