Skip to content

Commit 11a5116

Browse files
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

File tree

0 commit comments

Comments
 (0)