docs: document actual release-tagging contract#28
Merged
Conversation
AGENTS.md said "Tag releases as v2, v3, etc. (major only). Use floating major tags." but every release since v1 has actually shipped both an immutable patch tag (v2.0.0, v2.0.1, …, v3.0.0, v3.0.1) AND a floating major tag (v2, v3) force-updated to the latest, plus a GitHub release for each immutable tag. The prior wording was correct about the floating tag but silent on the immutable tag and the GitHub release, so a new agent following the instruction literally would skip exactly the reproducibility mechanism downstream consumers rely on when pinning to an exact commit. Replace the bullet with the same contract local-mutex already documents in its own AGENTS.md — immutable patch tag that is never force-moved, floating major tag that is force-updated every release, plus a GitHub release — so both published-action repos describe the same release shape and future agents cut tags the same way. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…on refs Three small README fixes folded into the same docs PR: 1. The "Limitations" section said callers must invoke `curlewlabs-com/local-cache/save@v2` even though every other example in the README (and on the marketplace) uses `@v3`. Fix the stale tag. 2. The "Upgrading from v1" section referred to "the first v2 restore" and "After upgrading to v2". That wording was correct when v2 was the current action version and doubles as a reference to the on-disk marker format (which is still "v2"), but for readers landing on this page today it reads as a contradiction with the surrounding `@v3` examples. Drop the v-number from the upgrade narrative — the instruction is the same regardless of which major version users are moving to. 3. The "Releasing" section said "Users pin to @V3 (floating major tag)" and then showed only the floating-tag commands. The companion AGENTS.md bullet (updated in this same PR) describes the full contract: both an immutable `vMAJOR.MINOR.PATCH` tag and the floating `vMAJOR` tag ship on every release, matching what every release since v1 has actually done. Bring the README into sync with AGENTS.md so a reader gets the same instructions from either entry point. Co-Authored-By: Claude Opus 4.7 (1M context) <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
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.
Problem
AGENTS.md said:
But every release since v1 has actually shipped both an immutable patch tag (v2.0.0, v2.0.1, …, v3.0.0, v3.0.1) AND a floating major tag (v2, v3) force-updated to the latest, plus a GitHub release for each immutable tag. The prior wording was correct about the floating tag but silent on the immutable tag and the GitHub release, so a new agent following the instruction literally would skip exactly the reproducibility mechanism downstream consumers rely on when pinning to an exact commit.
README.md had three related stale bits:
curlewlabs-com/local-cache/save@v2— every other example in the README uses@v3.@v3examples.Changed behavior
save@v2→save@v3.Invariants / risks
v3.0.2) and force-update@v3on merge so the floating major tag keeps tracking the exactmainHEAD. A driftingv3vs.mainwould undermine the invariant the new wording describes.Verification
Comparison against local-mutex AGENTS.md shows the two repos now describe the same release contract. README sections no longer reference the pre-v3 action tag.