Description
ADR 0012 specifies that the current stable codebase lives on an n.x branch (for instance a literal 1.x) and that stable releases are published from it. While implementing the Verawood stable releases (#244) we found this is not achievable with semantic-release.
A branch whose name matches the maintenance pattern (N.x, N.N.x) is classified by semantic-release as a maintenance branch. Maintenance branches can only publish patches to a major that has already shipped; they cannot originate a major's first stable release. With only 1.0.0-alpha.* prereleases in history, the 1.x maintenance range collapses to the empty >=1.0.0 <1.0.0 and 1.0.0 cannot be published (EINVALIDNEXTVERSION). There is also a bootstrap deadlock: 1.x cannot reach 1.0.0 until a higher 2.0.0-alpha line exists, while main cannot bump to 2.0.0-alpha until a stable 1.0.0 baseline exists.
The proposed amendment is to publish the current stable from a long-lived release branch instead. A release branch is a true release branch in semantic-release terms: it owns the latest dist-tag and can graduate the alphas to 1.0.0 in a single push, with no placeholder branch and no deadlock. The configuration reduces to a release entry plus a main prerelease entry.
The n.x branches are retained, but only to maintain superseded majors. When main's breaking work is ready to become the next major, an n.x branch is cut from release to keep patching the outgoing major, and main graduates onto release as the new current stable. Because the outgoing major has already shipped by then, the n.x maintenance branch works cleanly. This matches semantic-release's intended branch lifecycle.
Update ADR 0012 (section 3 and the related backport wording) to describe release as the current-stable branch and n.x branches as maintenance for superseded majors.
Description
ADR 0012 specifies that the current stable codebase lives on an
n.xbranch (for instance a literal1.x) and that stable releases are published from it. While implementing the Verawood stable releases (#244) we found this is not achievable with semantic-release.A branch whose name matches the maintenance pattern (
N.x,N.N.x) is classified by semantic-release as a maintenance branch. Maintenance branches can only publish patches to a major that has already shipped; they cannot originate a major's first stable release. With only1.0.0-alpha.*prereleases in history, the1.xmaintenance range collapses to the empty>=1.0.0 <1.0.0and1.0.0cannot be published (EINVALIDNEXTVERSION). There is also a bootstrap deadlock:1.xcannot reach1.0.0until a higher2.0.0-alphaline exists, whilemaincannot bump to2.0.0-alphauntil a stable1.0.0baseline exists.The proposed amendment is to publish the current stable from a long-lived
releasebranch instead. Areleasebranch is a true release branch in semantic-release terms: it owns thelatestdist-tag and can graduate the alphas to1.0.0in a single push, with no placeholder branch and no deadlock. The configuration reduces to areleaseentry plus amainprerelease entry.The
n.xbranches are retained, but only to maintain superseded majors. Whenmain's breaking work is ready to become the next major, ann.xbranch is cut fromreleaseto keep patching the outgoing major, andmaingraduates ontoreleaseas the new current stable. Because the outgoing major has already shipped by then, then.xmaintenance branch works cleanly. This matches semantic-release's intended branch lifecycle.Update ADR 0012 (section 3 and the related backport wording) to describe
releaseas the current-stable branch andn.xbranches as maintenance for superseded majors.