Commit 11a5116
authored
docs(readme): batched corrections + delete floating v1 tag (#8)
* docs(readme): correct the SHA-pin comment section
The previous version conflated SHA-pinned and tag-pinned semantics:
it claimed pinning '@<sha> # v1' leaves a security window where a
compromised maintainer could move the v1 tag to a malicious commit.
That's wrong. With SHA pinning, the 40-char hash is what GitHub
resolves; the comment is documentation. Moving the v1 tag has zero
effect on a SHA-pinned workflow. Both '# v1' and '# v1.0.2' as comments
are equally secure.
Rewrite the section to reflect the actual tradeoff (cosmetic only) and
highlight that the auto-updater normalizes to exact-release form on
first update regardless of what you typed.
* docs(readme): batched corrections across 9 findings
1. Tagline: 'SHA-pinned uses:' -> 'uses:' (scanner handles any uses ref,
not just already-SHA-pinned ones)
2. Intro bullet: 'signed, CI-triggering PR' -> 'CI-triggering PR
(optionally SSH or GPG-signed)'
3. Quickstart now SHA-pins the action itself so the example matches the
action's own guidance (previously pinned @v1, which suggested the
action excluded itself from its own recommendations)
4. Removed all references to the floating v1 tag: consumers should pin
by commit SHA with the exact release name as comment
5. Versioning section: removed 'Consumers typically pin to @v1' and
'despite the irony' phrasings that misrepresented current guidance
6. GPG setup: added complete caller-side YAML example to match SSH
section, plus a note that the GPG path is implemented but not yet
end-to-end validated in production
7. SSH/GPG table: 'CI agent' -> 'Persistent agent' (clearer)
8. Troubleshooting heading for semver warning now matches the real log
output instead of using the internal code variable name
9. Troubleshooting: added the 'Actions must be pinned to a full-length
commit SHA' org-policy error entry
Also: removed the 'Security design notes' section. The 'attackers reading
a public repo gain reconnaissance' framing read as security-through-
obscurity (or worse, as implying open source is bad). The useful content
(required inputs fail-fast; optional inputs use generic placeholders) is
implicit in the Inputs section already.
* docs(readme): brand-voice pass — calmer, less marketing cadence
Applies the brand-writer rubric: fluent, calm, direct syntax. Removes
em-dash-driven prose rhythm and the 'it's not X, it's Y' mirroring.
Splits long run-on sentences. Drops the slight sell-tone in a few
callouts (e.g. 'should be supplied because there is no sensible
fallback' is now just 'Required. A silent fallback would surprise
...').
No behavior changes. No factual changes. Only prose edits.
- All technical terms preserved (SHA, strict-semver, ssh-keygen,
gpg-agent, workflow_dispatch, Conventional Commits, etc.)
- All YAML, all commands, all SHAs, all tag names unchanged
- Section structure unchanged
- 21 remaining em dashes are all list-item value separators
('- both — create or update a tracking issue and open a PR').
Zero em dashes in running prose.1 parent 0d95f1e commit 11a5116
1 file changed
Lines changed: 150 additions & 118 deletions
0 commit comments