Next release channel

The next branch is a long-lived prerelease channel for publishing packages before they are promoted to the stable release flow. Releases from this branch publish prerelease versions to npm under the next dist-tag, so users can install them explicitly without moving the stable latest tag.

Branch setup

The next branch intentionally carries .changeset/pre.json:

{
  "mode": "pre",
  "tag": "next"
}

Keep this file in prerelease mode on next. The tag must stay next so Changesets publishes prerelease packages with the npm next dist-tag.

Do not put master into the next prerelease mode. Current master should not have .changeset/pre.json; stable releases from master continue to publish as normal and move latest only through the regular stable release process.

Regular operation

Bring stable branch updates into next as needed, either by merging master or by cherry-picking specific commits:

git switch next
git fetch origin
git merge origin/master

If the merge conflicts on .changeset/pre.json, resolve the conflict by keeping the next branch prerelease file with "mode": "pre" and "tag": "next".

Feature work can also land directly on next when it needs prerelease validation before promotion. Include normal Changesets for user-facing package changes; the release workflow will turn those changesets into generated prerelease version commits on next.

Promoting work back to master

Do not merge next wholesale back to master. Promotion should copy only the human-authored feature work that is ready for stable release:

git switch master
git fetch origin
git cherry-pick <feature-commit-sha>

Cherry-pick source, docs, tests, and normal changeset commits that describe the feature. Never cherry-pick generated Version Packages (next) commits from next to master.

When promoting, exclude release-generated files from the cherry-pick if they are present in the selected commits:

• .changeset/pre.json
• package CHANGELOG.md files
• version-only package.json changes

Those files are generated separately by the stable release workflow after the promoted changesets land on master.

If a cherry-pick includes both feature code and generated release changes, use a non-committing cherry-pick and reset generated release files before committing. Restore prerelease metadata and generated changelogs outright, then inspect package manifests hunk-by-hunk so version-only changes do not move to master:

git cherry-pick --no-commit <feature-commit-sha>
git restore --staged --worktree \
  .changeset/pre.json \
  'packages/*/CHANGELOG.md' \
  'packages/plugins/*/CHANGELOG.md'
git restore --source=HEAD --staged --worktree -p \
  -- 'packages/*/package.json' 'packages/plugins/*/package.json'
git diff -- packages
git commit

During the interactive git restore -p, drop version-only package package.json changes generated by the next release. Keep dependency, script, export, or metadata changes only when they are part of the promoted feature.

Release workflow and Chrome extension

The release workflow runs on both master and next. On next, Changesets publishes prerelease packages to npm using the next dist-tag.

Chrome extension publication is also branch-specific:

• master publishes the production extension listing. Its extension ID is hard-coded in .github/workflows/release.yml, and it uses the existing CWS_CLIENT_ID, CWS_CLIENT_SECRET, and CWS_REFRESH_TOKEN secrets.
• next publishes the prerelease extension listing with NEXT_CWS_EXTENSION_ID, NEXT_CWS_CLIENT_ID, NEXT_CWS_CLIENT_SECRET, and NEXT_CWS_REFRESH_TOKEN.

Keep those listings and credentials separate. Changes to the next listing should not affect the production Chrome Web Store listing used by master.