[thomson-t]

Why

Once work on the next major release starts, apps that stay on the current major still need fixes, so that major needs its own release branch. The release workflows can already publish from such a branch, but its releases never become the version a plain install picks up, even before the next major exists. A maintenance branch can also draft a major release by mistake, and none of the steps are written down. Once this lands, the current major's branch can be cut from main and released from straight away.

Programme

Part of preparing the next major release; the plan is internal and cannot be linked.

What changes

Before: Release Draft runs on any branch and offers a major bump everywhere. Release Publish tags main releases latest and maintenance releases maintenance-<major>.x, whatever is already on npm.

After:

• Release Draft runs only on main or a maintenance/<major>.x branch, and drafts a major bump only from main.
• Release Publish decides the npm dist-tag against npm's current latest.
  • A stable release takes latest only when it is newer. So a maintenance release ships as latest until the next major is out, then as maintenance-<major>.x.
  • A release from main that is not newer stops with an error instead of moving latest backwards.
  • The GitHub release is marked latest the same way.
  • Publishes from different branches run one at a time.
  • The rule is a small script with its own checks, run by the pull request workflow like the existing change classifier.
• The workflow security scan also runs on pushes to maintenance branches.
• A new RELEASING.md covers release lines, dist-tags, and cutting and patching a maintenance branch; the README's publishing note points to it. The changelog is generated at release.

This also needs a repository setting, which this pull request doesn't change. The npm-publish environment deploys only from main, so an admin must allow maintenance/* before the first maintenance release. RELEASING.md makes this the first step of cutting a branch.

Start reading at .github/scripts/npm-dist-tag.sh and its checks, then the publish-npm job.

Linked work

Unblocks: cutting maintenance/5.x from main (planned, once this merges).
Related: the same release rules in mParticle's React Native SDK, mParticle/react-native-mparticle#420.

Rollout

Path: merging changes the release workflows on main; nothing is published until a release is drafted and merged. A maintenance branch cut afterwards inherits the changes.
Feature flags: none.
Turning it off: revert this pull request; the workflows change when the revert merges.
What we watch: the next Release Publish run. Its "Resolve npm dist-tag" step logs the version, the chosen tag and npm's latest, which is 5.1.2 today. Afterwards npm view @rokt/react-native-sdk dist-tags should show latest on the newest version. A failed step or a latest that moved backwards means revert; one correct release means it has settled.

Risks

• A release from main is refused as not newer than latest; only happens when versions are out of order, and the error names both; we would see Release Publish fail at "Resolve npm dist-tag".
• A maintenance release takes latest after the next major has shipped; prevented by the comparison and by running publishes one at a time; we would see latest on an older major.
• The registry lookup fails mid-release; the job stops before publishing and can be re-run; we would see the step fail.
• The first maintenance release is rejected by the npm-publish environment; not addressed in code, since it is a repository setting documented as the first step of cutting a branch; we would see "Branch is not allowed to deploy".

Risk class: low.

Who

Written by: an automated coding agent (Claude Code), at an engineer's request, following an internal plan.
Code reviewed before opening: an independent review agent; it found that the npm-publish environment only allows main and that the documented maintenance install command would fail, both fixed. No person yet.
Design reviewed before opening: an engineer approved the plan on 21 October 2026.
Decision this implements: an engineering decision of 20 October 2026 to keep the current major on a maintenance branch and land the pipeline changes first; internal, cannot be linked.
Checked: on 21 October 2026, locally: the dist-tag checks (10 of 10); the script against the live registry (5.2.0 from a maintenance branch gets latest while latest is 5.1.2, and 5.1.0 from main stops with an error); the branch check; the workflow files parse; trunk check on the changed files.
Not checked: the release workflows on GitHub, which run only on dispatch or a VERSION change; the workflow security scan, which runs on this pull request.

Size

Hand-written: 180 lines (176 added, 4 removed) across 8 files.
Generated: none.

🤖 Generated with Claude Code

[paved-road-agent]

🛣️ Rokt Platform Paved Roads Scan Complete

✅ No paved-road issues detected

Scanned files against 188 rules. · Reviewed commit: 9d7ee91c65

📜 Scan history (1 scan)

Commit	Time (UTC)	Status	Findings
9d7ee91	2026-10-21 17:22:52	✅ success	0

ℹ️ About Rokt Platform Paved Roads Agent

This scan was performed by the Rokt Platform Paved Roads Agent, an automated paved-road standards review tool for pull requests. See the User Guide for details on severity levels, feedback reactions, and scan configuration.

Reply @paved-road-agent help for the list of commands you can run on this PR.

[pr-security-agent]

🔒 Security Scan Complete

✅ No security issues detected

Scanned files against 88 rules. · Reviewed commit: 9d7ee91c65

📜 Scan history (1 scan)

Commit	Time (UTC)	Status	Findings
9d7ee91	2026-10-21 17:22:52	✅ success	0

ℹ️ About PR Security Agent

This scan was performed by PR Security Agent, an automated security review tool for pull requests. See the User Guide for details on severity levels, feedback reactions, and scan configuration.

Reply @pr-security-agent help for the list of commands you can run on this PR.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.