docs: rewrite maintaining guide for the v3 branch and release model - #65
Merged
Conversation
The guide predated the v3 rework and contradicted itself: it gave the module path as /v3 while describing main's purpose as "active development for v2.x releases", never mentioned the next branch or release/v2, and described ci.yml as PR-only when it also runs on push and tags. More consequentially, it told authors their PR description becomes release notes "when squash-merged" without qualification. That is right for merges into next and wrong for promoting a line into main: squashing collapses the line into one commit and destroys every BREAKING CHANGE footer, so semantic-release would analyse a single commit against main's last tag. For the pending v3 promotion that computes v2.14.0 rather than v3.0.0 — an invalid tag for a /v3 module path, and only visible once published. Document the branch table, the merge-commit rule with its reasoning, a pre-promotion checklist including the expected informational gorelease result, and the actual workflow triggers.
Simulating both merge strategies locally and running semantic-release --dry-run gives 3.0.0 for a merge commit and 2.14.0 for a squash, with 0 of the 22 BREAKING CHANGE footers surviving the squash. State the numbers and include the commands so a maintainer can re-check before any promotion instead of trusting the claim.
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.
Why now
This file is a hazard for the pending v3 promotion.
It predated the v3 rework and contradicted itself — module path given as
/v3, butmain's purpose described as "active development for v2.x releases". It never mentioned thenextbranch orrelease/v2, and describedci.ymlas PR-only when it also runs on push and tags.The consequential part: it told authors their PR description becomes release notes "when squash-merged", unqualified.
That is correct for merges into
next. It is wrong for promoting a line intomain:semantic-release would then analyse a single commit against
main's last tag (v2.13.1) and computev2.14.0instead ofv3.0.0— an invalid tag for a module whose path is/v3, and only visible once published.Change
main/next/release/v2/release/v1with their module paths, status and release patterns.Inferred base version: noneis the expected result on the release PR, not a failure.go vetstep exists separately fromtask check.CONTRIBUTING.mdfor contributor-facing process rather than duplicating it.All relative links verified to resolve.