Repository navigation
docs: reflow architecture.md to reduce merge conflicts - #564
Closed
jussielo-amd wants to merge 2 commits into
Closed
jussielo-amd wants to merge 2 commits into
jussielo-amd wants to merge 2 commits into
Conversation
Per-crate sections were single-line paragraphs, so concurrent PRs editing the same crate's narrative (common during EAI-7768's one-cluster-at-a-time modularization) collided on that one line even when their edits were unrelated sentences. Reflow to one sentence per line and bullet-ify module lists so an appended extraction is a new line, not a rewritten paragraph. No content changes; verified against cargo xtask check-architecture-doc and its full unit test suite. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
parse_gpu_indices_arg and optional_arg were moved back to lib.rs in the "Review fixup" of 1845df3 (common.rs's own extraction PR, #479) since they didn't meet the module's >=2-caller admission rule, but the doc's "small arg/healthcheck/endpoint-key utilities" wording wasn't updated to match. Drop "arg/" — common.rs has no arg-parsing helpers; the healthcheck/endpoint-key claims are accurate. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The documentation-only restructuring is accurate and introduces no unresolved issues.
Review effort: Balanced
Findings: None
What changed in this PR
Reformats the architecture guide to reduce merge conflicts while preserving its meaning and correcting one stale common.rs description.
Changes:
- Applies sentence-level line breaks.
- Converts module narratives into structured lists.
- Removes the outdated claim that
common.rscontains argument utilities.
| File | Description |
|---|---|
docs/architecture.md |
Reflows and restructures the module map for conflict-resistant editing. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
jussielo-amd
marked this pull request as ready for review
October 6, 2026 10:03
jussielo-amd
enabled auto-merge
October 6, 2026 10:08
jussielo-amd
marked this pull request as draft
October 6, 2026 12:58
auto-merge was automatically disabled
October 6, 2026 12:58
Pull request was converted to draft
jussielo-amd
added a commit
to jussielo-amd/rocm-cli
that referenced
this pull request
Oct 7, 2026
* ci: add lychee gate for markdown links (ROCm#578) docs/architecture.md's path citations are about to move to explicit markdown links instead of bare backtick filenames, checked by an off-the-shelf link checker instead of a hand-rolled parser (see ROCm#578). This adds that checker now, additively: it only looks at links that already exist, so it can land independently of the citation rewrite and doesn't conflict with ROCm#493/ROCm#564, which are still editing docs/architecture.md's prose. Scoped offline (no network) to avoid external-host flakiness, and excludes docs/rocm-docs/ (Sphinx/MyST source whose cross-doc anchors are resolved by the docs-build job, not plain markdown). Signed-off-by: Jussi Elo <jussi.elo@amd.com> * fix(docs-links): correct overclaim, document the new CI gate lychee.toml's comment said it replaces architecture_doc.rs's checker; that checker is untouched and still runs, so say "first step toward replacing" instead. Also add the docs-links gate to CONTRIBUTING.md's list of enforced CI invariants, next to check-architecture-doc. Signed-off-by: Jussi Elo <jussi.elo@amd.com> * fix(docs-links): narrow CONTRIBUTING.md's link-coverage claim The docs-links line said every link in the repo is checked, but lychee.toml runs offline (no external https:// links) and excludes docs/rocm-docs/ (Sphinx/MyST source, covered by docs-build instead). Say what the job actually covers and point at lychee.toml for the exclusion list, instead of overclaiming. Signed-off-by: Jussi Elo <jussi.elo@amd.com> --------- Signed-off-by: Jussi Elo <jussi.elo@amd.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
docs/architecture.mdto one sentence per line (semantic line breaks) — markdown collapses single newlines to a space, so rendering is unchanged.###crate section was a single very long markdown line. Git merges per line, so two PRs editing the same crate's section — common during EAI-7768's modularization effort, which lands "one cluster at a time" as sequential PRs against the same crate (e.g.apps/rocmd'spersistence.rsPR ROCMAI-83: extract persistence.rs from apps/rocmd/src/lib.rs #477 thencommon.rsPR ROCMAI-83: extract common.rs, webhook.rs, and cli.rs from apps/rocmd/src/lib.rs #479) — collided on that one line even though their actual edits were unrelated sentences. Smaller diff units (sentence/bullet instead of paragraph) make those edits mergeable without manual conflict resolution.common.rsentry said it holds "small arg/healthcheck/endpoint-key utilities," butparse_gpu_indices_arg/optional_argwere moved back tolib.rsin that same extraction PR's (ROCMAI-83: extract common.rs, webhook.rs, and cli.rs from apps/rocmd/src/lib.rs #479) "Review fixup" for not meeting the module's >=2-caller admission rule — the doc wording wasn't updated to match. Dropped "arg/"; the healthcheck/endpoint-key claims are accurate. This predates this PR (confirmed identical wording onorigin/main) — fixed here as a one-line drive-by since the line was already being touched.Test plan
cargo xtask check-architecture-docpasses (this is what CI'sarchitecture-docjob runs).cargo test -p xtask architecture_doc— all 48 unit tests pass, includingrun_passes_against_the_real_doc.Checklist