docs: fix stale @v1 action refs, document the Ports: trailer convention - #43
Merged
Merged
Conversation
The usage examples referenced aklivity/gitflow-changelog@v1 and merge-report@v1, but no v1 has ever been cut -- only v0.x releases and the moving v0 tag exist. Fixed both to @v0 to match reality. Also adds a "Recommended: writing a port commit merge-report can recognize" section covering the full-port (keep subject verbatim) vs partial-port (Ports: <sha> trailer) convention, so anyone adopting merge-report sees it documented up front instead of having to reverse-engineer it from ports-trailer.ts. Cites the first real-world use (aklivity/zilla-plus PR #1054) as confirmation it works end-to-end.
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.
Summary
Reviewed
README.mdend to end for accuracy while documenting thePorts: <sha>trailer convention for new adopters.Fixed a real staleness bug: the usage examples referenced
aklivity/gitflow-changelog@v1andaklivity/gitflow-changelog/merge-report@v1, but the project has never cut a v1 — onlyv0.xreleases and the movingv0tag exist (confirmed against the actual tags: latest isv0.6.2,v0points at the same commit). A new user copy-pasting the old example would reference a tag that doesn't exist. Fixed both to@v0.Added a new "Recommended: writing a port commit merge-report can recognize" section, covering:
(#NNN)should differ).Ports: <original-sha>trailer instead, since no title convention can bridge a genuine content difference.This was previously only documented as an internal convention in a private consuming repo's
AGENTS.md; this makes it visible to anyone adoptingmerge-reportdirectly from the README, without having to reverse-engineer the convention fromports-trailer.ts.Cites the first real-world confirmation that the trailer resolves end-to-end (
aklivity/zilla-plusPR #1054,Ports: 51d29db...), matching the existing README style of citing real validation data (e.g. the "86 raw candidates reduced to 9" note already there).No code changes —
npm run typecheckre-run clean to confirm the tree is otherwise untouched.Generated by Claude Code