Restructure the README to the portfolio standard - #8
Merged
Conversation
The README was 13,604 bytes and carried the whole consumer manual. It is now 7,652 bytes and covers only what an infrastructure repo needs: what consumes it, how a consumer calls it, the version contract, and how to change it without breaking the callers. Nothing was dropped — the detail moved into docs/ and is linked from the README. Moved out: - docs/macos-release.md — release/CI caller snippets, the input tables, the release-script env contract, the Homebrew cask PR flow, the gen-1 -> gen-3 secret rename table and the migration sequence. - docs/self-hosted-runners.md — the private-repositories-only rule, the two gates that enforce it, and the fleet behaviour changes. - docs/design-decisions.md — the design-decisions list, extended with the paired-cleanup requirement and the per-account status hub rationale. Corrected: - The "Pinning model" section claimed the composite actions are referenced as @main, and that a push to main therefore changes behaviour under consumers pinned at @v1. Both statements are wrong. Every internal reference is @v1, and has been at every released tag (v1.0.0 through v1.2.0). The real consequence is the opposite and is now documented: a push to main is inert, and an exact workflow pin still resolves its composite actions through the moving v1 tag. - The Contents table omitted ios-release.yml, project-status.yml and actions/project-status. All three are listed now. - setup-apple-keychain was described as importing a "Developer ID" cert. ios-release.yml also uses it for an Apple Distribution cert, so the description no longer names one certificate type. Also: - docs/ios-release.md opened with an unapplied "README patch" instruction block telling a reader to paste its contents into the README. Replaced with a title; the body is untouched. - Consumer repositories are named and counted from a code search rather than asserted. Only the two public consumers are linked — the other four are private, so linking them would have produced four 404s. - Added the status and licence badges. No CI badge: every workflow here is workflow_call-only, so there is no default-branch run for one to report. Co-Authored-By: Claude Opus 5 <noreply@anthropic.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
2 participants
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 this README onto the shared portfolio structure for infrastructure repos: what consumes it, how a consumer calls it, the version contract, how to change it safely, licence.
Size: README.md 13,604 → 7,652 bytes. Nothing was deleted; the detail moved into
docs/and is linked from the README.Wrong facts removed
privacykey/gh-workflows/actions/<name>@main" — they are not, and never were at any released tag. Every internal reference is@v1, atv1.0.0,v1.1.0andv1.2.0alike.mainhere changes behaviour under consumers pinned to@v1" — the opposite is true, and it is the single most important thing a maintainer needs to know before editing this repo. A push tomainis inert for consumers; moving thev1tag is the release action. The README now says that, and documents the real subtlety instead: an exact workflow pin (@v1.1.0) still resolves its composite actions through the movingv1tag, so it is not a full freeze..github/workflows/ios-release.yml,.github/workflows/project-status.ymlandactions/project-status. The iOS release pipeline, which is the largest workflow here, was undocumented in the README entirely.actions/setup-apple-keychainwas described as importing a "Developer ID cert."ios-release.ymlalso uses it for an Apple Distribution certificate, so the description no longer names one certificate type.docs/ios-release.mdopened with an unapplied "README patch" instruction block — an HTML comment telling the reader to paste two chunks into the README, which never happened. Replaced with a title. The body is untouched, and the README links it.Dead links avoided
There were no dead links in the old README (it contained no external links at all). Four would have been introduced by the obvious version of the new "What consumes this" section: four consumers of this repo are private and return 404 to anyone reading this public README. They are counted, not named or linked. Only
privacycommandand.githubare linked; both verified 200.Consumer counts
Verified by code search across all three accounts rather than asserted: six repositories, using
macos-sparkle-release.yml@v1,macos-app-ci.yml@v1,ios-release.yml@v1,project-status.yml@v1andassert-trusted-runner@v1(the guard is called from nine workflows in total).Badges
Status and licence only, both verified to resolve. No CI badge: every workflow in this repo is
workflow_call-only, so there is no default-branch run for a badge to report. No release badge: there are no published GitHub Releases — the tags are the whole contract, which the README now states.The status badge is currently live and reads "Maintained". If it briefly renders "resource not found", that is the status hub PR still merging; the endpoint path is correct.
Content moved, not deleted
docs/macos-release.md— caller snippets, input tables, release-script env contract, Homebrew cask PR flow, gen-1 → gen-3 secret rename table, migration sequence.docs/self-hosted-runners.md— the private-repositories-only rule and the two gates enforcing it.docs/design-decisions.md— the design-decisions list.Note, out of scope
just lintcurrently reports two pre-existingactionlintfindings inios-release.yml(avarscontext at line 191 and an SC2012lsusage at line 890). Not touched by this PR.