Repository navigation
Bring the README Into the Fleet Structure - #477
Merged
Merged
Conversation
Six audit findings against spec/readme-structure.md and spec/third-party-tools.json. - Renamed Use Cases to Overview, the declared name for that slot, which has no accepted aliases. - Moved Installation above Usage, the declared relative order. - Regenerated the Table of Contents for the rename and the move, and verified every anchor resolves to a heading. - Renamed [license-link] to [license]. It points at a path in this repository, and those carry a bare name with no suffix. - Regrouped the reference definitions into the five declared groups, Shields, Distribution, Repo, and External, replacing the four local group names. Each group is sorted by reference name alone. All 64 definitions are used and none is undefined. - Took the fleet catalog's description for all eleven shared tools, corrected the Nerdbank.GitVersioning link from the marketplace action to the project, and used the declared lead-in wording. The separator is a colon rather than a spaced hyphen, matching the shipped fleet adoption and the dash rule. Verified: the full Docker doc-lint set, the diff-scoped prose gate, and all three repo-gate checks.
The local strict review pass found 31 inline links surviving outside the Table of Contents and the code fences: 7 in-page anchors and 24 uses of 21 in-repo paths. The spec's Style section allows the Table of Contents as the single exception and requires reference-style everywhere else, and its Reference Links table declares the Sections group for in-page anchors and the Repo group for paths inside this repository, both bare with no suffix. The reviewer called this pre-existing and out of scope, which is true of the condition and not of this PR: bringing the README into the fleet structure is what this change is for, and leaving them inline would leave the file violating the rule the rest of the commit enforces. The definition block now carries all five declared groups. Verified that all 92 references resolve with none undefined and none orphaned, that every anchor matches a real heading, and that every repo path exists on disk.
Converting the last inline links pulled two pre-existing callout lines into the prose gate's diff scope, where their emoji fail as unclassified characters: INFORMATION SOURCE (U+2139) and VARIATION SELECTOR-16 (U+FE0F) sit in no tier, and the tiers live in a verbatim carried section this repo cannot extend. Fixed all seven rather than the two in scope. Fixing only those would leave one file carrying two callout styles, and would leave the same failure waiting for whichever change next touches one of the other five lines. The warning callout keeps its distinction from the notes by taking the label Warning rather than Note, which is the only signal its emoji was carrying. README.md is now pure ASCII.
The prose gate's semicolon rule reads the one inside TL;DR, so the two callouts the emoji cleanup touched now open on Summary. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nothing in this repository or the hub workflows it calls uses the Git Auto Commit action, so the 3rd Party Tools list no longer claims it. A trailing backslash ended a list item, which CommonMark renders as a literal backslash. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
 |
Owner
Author
|
A recorded local strict-review pass covers head |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #477 +/- ##
========================================
Coverage 87.68% 87.68%
========================================
Files 11 11
Lines 1941 1941
Branches 252 252
========================================
Hits 1702 1702
Misses 166 166
Partials 73 73 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for the README update, which is described as aligning its structure and audit findings with the fleet specification.
No open issues 🎉
What changed in this PR
This PR brings README.md into the fleet README structure. The fleet spec sets the section names and order, the link layout, and the 3rd Party Tools entries. The work was parked on an older branch and is now rebased onto develop. It closes the README findings from the latest audit.
Changes:
- Renames
Use CasestoOverviewand movesInstallationbeforeUsage. - Converts inline links to reference-style links, grouped under the spec's headers (Sections, Shields, Distribution, Repo, External).
- Gives each 3rd Party Tools entry a short description. Nerdbank.GitVersioning now links to the library, and Git Auto Commit is removed.
- Replaces emoji callouts with plain labels, and fixes a list item ending in a stray backslash.
| File | Description |
|---|---|
| README.md | Aligns section names, order, links, callouts, and 3rd Party Tools entries with the fleet README spec. |
Review effort: Lite
Adds cspell, dotnet-outdated, editorconfig-checker, and markdownlint-cli2 with their fleet catalog descriptions, since the list already names the hub-workflow actions this project depends on. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
A recorded local strict-review pass covers head |
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.
Brings
README.mdinto the fleet README structure (spec/readme-structure.md,spec/readme-sections.json,spec/third-party-tools.jsonat hubmainc175d557). This is the third of three pull requests for this cycle. It closes the 16 README findings inaudit run 2026-11-09T16:23:53Z | hub c175d557 | branch override develop.This is the README work parked since 2026-09 on
resync/readme-structure, which never opened as a pull request. It waited on ptr727/ProjectTemplate#1190, which is now closed. Its three commits cherry-picked cleanly onto currentdevelop, and two follow-ups were added.Changes
Use CasesbecomesOverview, andInstallationnow precedesUsage.[license-link]becomes the bare[license].TL;DRcallouts now readSummary, because the prose gate's semicolon rule fires onTL;DR(filed as prose_lint's Semicolon Check Fires on the Semicolon Inside TL;DR ProjectTemplate#3954).\, now ends in a period.Findings left open after the local review budget
The local strict review ran two rounds (3 findings, then 3). The first round's two findings on this change's text are fixed above. Its third reappears below. The second round's findings are listed here with their class, per
local-strict-review"Disposing of Findings":introduced, README.md:556: 3rd Party Tools did not list four tools the repository uses that the hub catalog names. Fixed in1057c75at the maintainer's direction: cspell, dotnet-outdated, editorconfig-checker and markdownlint-cli2 now carry their catalog descriptions. A third local pass over that commit recorded 0 findings.Pre-existing findings, not filed
pre-existing, README.md:574 and the four other link-group headers: if nuget.org renders the packed README with raw HTML disabled, the<!-- ... -->headers show as literal text on the package page.developalready carried four of these headers. The fleet spec requires them, so any fix belongs to the hub spec. This is inferred, not observed. Check it on the next published package page.pre-existing, README.md:96: on nuget.org, the TOC anchor#3rd-party-toolsmay not resolve if the gallery's heading ids drop leading digits. This line is unchanged by this branch. Also inferred, not observed.pre-existing, README.md Repo link group: relative links (./WORKFLOW.md,./LICENSE, ...) are likely dead on the nuget.org package page.develophad the same relative links inline. The fleet spec's Repo group calls for repo-relative paths.Verification
🤖 Generated with Claude Code