Skip to content

Hold the README shape constant across repository visibility#511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ptr727 merged 2 commits into from
Aug 1, 2026
Merged

Hold the README shape constant across repository visibility #511

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
056115c
Hold the README shape constant across repository visibility
ptr727 Aug 1, 2026
d741f20
Restructure the sentence rather than capitalize the tool name
ptr727 Aug 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions spec/readme-structure.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -24,6 +24,8 @@ The preferred `README.md` shape for a fleet project. The audit's `readme-structu

Shields are not a top-level section. They live under **Build and Distribution** as the **Build Status** and **Releases** sub-sections. Each shield is a reference-style link, with the definitions grouped under `<!-- Shields -->` at the bottom of the file. Stack a group's badges by ending each line except the last with a trailing backslash.

**Repository visibility does not change the structure.** A private repo carries the same sections and the same shield set as a public one, written in full. A private repo cannot be read by shields.io, so its GitHub-sourced badges render broken until it goes public, and that is accepted rather than worked around. The alternative, writing a reduced README while private and adding the missing shields at the visibility flip, makes the shape depend on a property that is temporary by design, since a repo is usually private precisely **while** it is being made presentable, which is exactly when its README is written. Carrying the full shape means going public is a visibility change and nothing else, with no README work owed at the flip and no second shape for the audit to accept.

## Style

- Write in the current state, present tense, so the reader needs no knowledge beyond what they are reading (GOVERNANCE.md Documentation Style).
Expand Down
Loading