docs(readme): batched corrections + delete floating v1 tag#8
Merged
Conversation
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.
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.
nerdalytics
changed the title
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.
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
1 participant
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.
Batched README fixes across 9 findings
uses:ref@v1floating-tag references removed: the Marketplace doesn't expose av1option anyway (only exact releases), and the whole "v1 vs v1.0.x" discussion only added confusion@v1" and "despite the irony" phrasingAlso removed the "Security design notes" section — the framing read as security-through-obscurity; useful content was implicit elsewhere.
Companion change (done separately after merge)
Delete the
v1floating git tag from the repo. beacon and tinywhale are SHA-pinned so the deletion is safe.No new release
This PR is docs-only. Marketplace listing will pick up the new README on the next natural release (driven by real behavior changes, not doc polish).