docs: consolidate run/debug-locally guide (Agent Ex Phase 3 PR 4)#12176
Draft
brooke-hamilton wants to merge 2 commits into
Draft
docs: consolidate run/debug-locally guide (Agent Ex Phase 3 PR 4)#12176brooke-hamilton wants to merge 2 commits into
brooke-hamilton wants to merge 2 commits into
Conversation
Delete the deprecated running-controlplane-locally.md and make radius-os-processes-debugging.md the single authoritative guide for running and debugging the Radius control plane locally. - Reformat the authoritative doc into the standard five-section format (Purpose -> Prerequisites -> Steps -> Verification -> Troubleshooting). - Verify every command, path, port, and make/debug target against the current code (build/debug.mk, .vscode/launch.json, start-radius.sh): add the missing k3d prerequisite, correct the Go version to 1.26+, document the k3d-cluster lifecycle and destructive debug-stop, add an endpoints/ports table, and add an explicit Verification section. - Repoint inbound links in contributing-code-control-plane/README.md, how-to.md, and contributing-code-tests/running-functional-tests.md. - Sync the annotated-example description in authoring-contributing-docs.md to the doc's new five-section structure. 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 consolidates the “run & debug locally” contributor guidance by making radius-os-processes-debugging.md the single authoritative workflow, deleting the legacy parallel guide, and repointing inbound links to the new location.
Changes:
- Removes the deprecated control-plane local-running guide and updates inbound links to point to the OS-process debugging guide.
- Reformats and expands the authoritative debugging guide into the standard Purpose → Prerequisites → Steps → Verification → Troubleshooting structure.
- Updates the “authoring docs” annotated example description to match the new five-section structure.
Review notes (blocking / important):
radius-os-processes-debugging.mdcurrently hard-wraps prose; repo Markdown conventions require single-line paragraphs (no manual wrapping).- The endpoints table is slightly inconsistent for UCP vs other components (UCP row omits
/healthz).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/contributing/how-to.md | Repoints the “run control plane locally” link to the authoritative debugging guide. |
| docs/contributing/contributing-code/contributing-code-tests/running-functional-tests.md | Updates prerequisite link to the new debugging guide. |
| docs/contributing/contributing-code/contributing-code-debugging/radius-os-processes-debugging.md | Becomes the single authoritative run/debug workflow; reorganized into the standard five-section format and updated for current automation. |
| docs/contributing/contributing-code/contributing-code-control-plane/running-controlplane-locally.md | Deleted legacy/duplicate guide. |
| docs/contributing/contributing-code/contributing-code-control-plane/README.md | Repoints index link to the new authoritative debugging guide. |
| docs/contributing/authoring-contributing-docs.md | Updates the annotated example text to reflect the new five-section structure. |
- Reflow hard-wrapped prose in radius-os-processes-debugging.md to single-line paragraphs, per the repo Markdown convention (.github/instructions/markdown.instructions.md). - Add the /healthz path to the UCP row of the endpoints/ports table for consistency with the other components and the debug-start health wait. - Fix grammar in running-functional-tests.md: "is setup" -> "is set up". - Permalink the inbound link in eng/design-notes/architecture/ 2024-05-radius-on-dapr.md to the commit SHA where running-controlplane-locally.md still exists, so the historical design note keeps pointing at the exact doc it referenced instead of 404ing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.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 4 (Running locally / debugging) of the Agent Ex — Phase 3 (Contributing docs) plan — see the PR 4 task under §6 of that plan.
Radius had two overlapping guides for running and debugging the control plane locally: an older one marked "Deprecated / Legacy" and a newer automated one. This PR deletes the old guide, makes the newer guide the single source of truth, rewrites it into the standard documentation format, and verifies every command and port against the current code.
Merge target
brooke-hamilton/agentex-phase3plan branch, notmain. It is one of seven stacked Batch A PRs; 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 Batch A PRs (and the PR 8/9 index work) land.Files changed
docs/contributing/.../contributing-code-control-plane/running-controlplane-locally.md— the old, manual guide that already carried a "Deprecated / Legacy" banner pointing at the new one. Its VS Code launch configs no longer exist in the repo.docs/contributing/.../contributing-code-debugging/radius-os-processes-debugging.md— now the single authoritative guide. Reformatted into the standard five-section layout (Purpose → Prerequisites → Steps → Verification → Troubleshooting) and corrected against the current code: added the missing k3d tool requirement, fixed the Go version to 1.26+ (matchesgo.mod), documented thatmake debug-stopdeletes the local cluster, added an endpoints/ports table, and added a Verification section.docs/contributing/.../contributing-code-control-plane/README.md— the index link now points to the new guide instead of the deleted file.docs/contributing/how-to.md— the "run control plane locally" link now points to the new guide.docs/contributing/.../contributing-code-tests/running-functional-tests.md— the "local dev environment is set up" link now points to the new guide.docs/contributing/authoring-contributing-docs.md— this file uses the debugging guide as a worked example; updated that description so it matches the guide's new structure.eng/design-notes/architecture/2024-05-radius-on-dapr.md— this historical design note linked to the deleted file via a…/blob/main/…URL. Pinned that one link to the commit SHA where the old guide still exists (a permalink) so the dated note keeps pointing at exactly the doc it referenced and no longer 404s. The surrounding narrative is unchanged.Notes for reviewers