From 056115c7560b255096b9efd161a3037a93555b48 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 1 Aug 2026 10:29:27 -0700 Subject: [PATCH 1/2] Hold the README shape constant across repository visibility spec/readme-structure.md stated no behavior for a private repo, so each one decided separately whether to write the GitHub-sourced shields that shields.io cannot read while private. PhotoCleaner carried Docker Hub shields only and planned to add the rest at the visibility flip. The maintainer's decision is that the structure does not vary. A private repo carries the same sections and the same shield set, written in full, and the broken badges are accepted until it goes public. The reason is that visibility is temporary by design. A repo is usually private precisely while it is being made presentable, which is exactly when its README is written, so keying the shape to visibility means writing the README twice and owing work at the flip. Carrying the full shape makes going public a visibility change and nothing else, and leaves the audit one shape to accept rather than two. Answers finding 3 of #509. Co-Authored-By: Claude Opus 5 (1M context) --- spec/readme-structure.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/readme-structure.md b/spec/readme-structure.md index 3174c221..bcfe0206 100644 --- a/spec/readme-structure.md +++ b/spec/readme-structure.md @@ -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 `` 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. shields.io cannot read a private repo, so its GitHub-sourced badges render broken until the repo 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). From d741f2067618d42bcbfc79eb1eb7c1ea73b842f9 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Sat, 1 Aug 2026 11:15:38 -0700 Subject: [PATCH 2/2] Restructure the sentence rather than capitalize the tool name The paragraph opened a sentence with "shields.io", which reads as a continuation and is the lowercase-opening problem the review flagged. The suggested fix was to write "Shields.io", which the repo's own rules forbid: CODESTYLE.md requires each tool's official casing in prose and says not to invent variants, and GOVERNANCE.md says to restructure so the sentence does not open on a lowercase tool name rather than capitalizing it against its official spelling. So the sentence now opens on the subject instead, which fixes the opening and keeps the tool's own casing. Co-Authored-By: Claude Opus 5 (1M context) --- spec/readme-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/readme-structure.md b/spec/readme-structure.md index bcfe0206..32c417d4 100644 --- a/spec/readme-structure.md +++ b/spec/readme-structure.md @@ -24,7 +24,7 @@ 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 `` 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. shields.io cannot read a private repo, so its GitHub-sourced badges render broken until the repo 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. +**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