Skip to content

docs: reflow architecture.md to reduce merge conflicts - #564

Closed
jussielo-amd wants to merge 2 commits into
mainfrom
docs/architecture-md-maintainability
Closed

jussielo-amd wants to merge 2 commits into
mainfrom
docs/architecture-md-maintainability

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Reflow every paragraph in docs/architecture.md to one sentence per line (semantic line breaks) — markdown collapses single newlines to a space, so rendering is unchanged.
  • Convert each per-crate section's module narrative into bullet lists (one bullet per extracted file), instead of one long run-on paragraph per crate.
  • Why: every ### 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's persistence.rs PR ROCMAI-83: extract persistence.rs from apps/rocmd/src/lib.rs #477 then common.rs PR 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.
  • Fixes one pre-existing stale claim found during review: the common.rs entry said it holds "small arg/healthcheck/endpoint-key utilities," but parse_gpu_indices_arg/optional_arg were moved back to lib.rs in 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 on origin/main) — fixed here as a one-line drive-by since the line was already being touched.
  • Everything else: no factual content changed — this is a formatting pass. Word-diffed the change to confirm no other claim was altered, only structure (parens → em-dash, bullets instead of inline lists).
  • Risk: low. Docs-only change, no code touched, verified against the CI gate that actually enforces this doc's correctness (below).

Test plan

  • cargo xtask check-architecture-doc passes (this is what CI's architecture-doc job runs).
  • cargo test -p xtask architecture_doc — all 48 unit tests pass, including run_passes_against_the_real_doc.
  • Manually word-diffed before/after to confirm only formatting changed (plus the one documented content fix above).

Checklist

  • N/A — no bug fix (no xfail rows to update).
  • N/A — no new subcommand/subsystem added.
  • N/A — no user-facing message changed.

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>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.rs contains 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
jussielo-amd marked this pull request as ready for review October 6, 2026 10:03
@jussielo-amd
jussielo-amd requested a review from a team as a code owner October 6, 2026 10:03
@jussielo-amd
jussielo-amd requested a review from rominf October 6, 2026 10:03
@jussielo-amd
jussielo-amd enabled auto-merge October 6, 2026 10:08
@jussielo-amd
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants