Meteor Version Bump Rules

Guidelines for bumping package versions across the Meteor repository for beta, RC, and official releases.

Branching Model

Releases are prepared on release-<VERSION> branches (e.g., release-3.4.1). The main development branch is devel.

• Changed packages = packages with diffs between devel and the release branch
• Always compare against devel to determine which packages need version bumps
• The release branch name determines the track number used in prerelease suffixes

Track Number Derivation

The track number is the release branch digits concatenated (dots removed):

Detecting Changed Packages

git diff devel --dirstat=files -- ./packages/

This is the same comparison used by the update-semver automation tool via scripts/admin/update-semver/get-diff.sh.

Prerequisites

Before bumping versions:

1. You must be on a release-* branch
2. All changes intended for the release must be merged
3. Confirm the release type with the user: beta, RC, or official

Modern Tool npm Packages

Include changed modern-tool npm packages such as @meteorjs/rspack in the same base-branch analysis:

Compare the full npm package directory with the base. Ignore only its current version field and matching lockfile version metadata when identifying shipped changes. Classify the rest as patch, minor, or major, then derive the target X.Y.Z release line from the base version.

Apply only the explicitly requested npm stage:

Never advance a sufficient version just because the workflow reruns. Increment beta.N or rc.N only when the user requests another prerelease after the current one was published. If the required magnitude rises, move to the new release line and reset the requested prerelease to .0. Never downgrade from RC to beta or from stable to a prerelease.

Do not infer the npm stage from the Meteor release stage. The current @meteorjs/rspack bump helper supports beta and stable versions, but not RC. Handle an explicitly requested RC version directly unless that helper changes.

After selecting the package version, use sync-modern-tool-versions to propagate it to the lockfile, install constants, normal fixtures, and active docs. The sync skill verifies the selected version but does not increment it or publish. Include the npm package in the bump table and apply it after confirmation. Keep packages/rspack/package.js independent and analyze it normally.

Version Format Reference

Two Distinct Schemes

1. meteor-tool — simple semver prerelease (no track number):

2. All other packages — encode the track number in the prerelease tag:

Version Transitions

Version Bump Magnitude

When creating the first beta for a release, each changed package needs a version bump from its current stable version. The magnitude depends on the nature of changes.

For subsequent betas, RCs, and official releases, the base version (X.Y.Z) stays the same — only the prerelease suffix changes.

Magnitude Rules

When NOT to Bump

Some changes don't warrant a version bump at all, even when files in a package change. A package should not be bumped if its only diff vs devel consists of:

• Lint / formatter changes — var → const, quote style (' → "), trailing commas, line-wrap reformatting, indentation, semicolons, function() { → function () {. No behavioral change.
• Test-only changes — additions or refactors of test files (*-tests.js, *-test.js, tests.js, files under Package.onTest). Tests don't ship to users.
• Comment / JSDoc-only changes — moved or reformatted comments with no code change.

If, after mentally stripping out these classes of changes, no runtime code change is left, do not bump the package. The release ships with the package at its current stable version.

Conversely, you MUST bump if any of these are present alongside lint/test/format:

• A change in a .js / .ts / .mjs file under the package's source (not a test file) that alters control flow, output, or external behavior
• A change in Package.describe version, summary, dependencies, or exports
• A change in Npm.depends() or Cordova.depends() versions
• A change in a .d.ts file that adds/removes/modifies the public type surface (a semicolon/quote-only .d.ts reformat is still lint-only and does not bump)

When unsure whether a diff is lint-only, stop and present the diff to the user.

How to Assess Each Package

For each changed package, Claude should analyze the diff to determine the bump magnitude:

git diff devel -- packages/<name>/

IMPORTANT — Auto-update safety rule: Meteor patch versions are picked up automatically by apps using ~ semver ranges. A patch bump that changes observable behavior can silently break apps on their next update. When in doubt, bump minor — it's always safer. Minor bumps require explicit opt-in, giving users control over when they adopt changes.

Check for minor bump signals:

• New functions or methods exported in package.js (api.export, api.addFiles for new files)
• New public methods added to existing classes (e.g., new assertion methods, new query helpers)
• New configuration options or capabilities that users can opt into
• Significant new features even without new exports (e.g., new bundler capabilities)
• Removed internal methods/functions — even _-prefixed methods, since Meteor users commonly monkey-patch internals
• Changed which implementation runs — e.g., switching from a polyfill to native, or replacing a dependency, even if the API is the same
• Behavioral changes in existing code paths — changed defaults, different error handling, altered timing/ordering, even if "correct"
• Changed HTML templates or UI content — packages that deliver HTML via addFiles (e.g., *-config-ui packages with OAuth setup instructions) produce different user-visible output when their templates change

Check for patch bump signals:

• Changes only to existing function bodies that fix clearly incorrect behavior (null checks, crash fixes, typo corrections)
• TypeScript type corrections (additive .d.ts changes only)
• Removed truly redundant code with provably identical behavior (e.g., return await → return in async function)
• Test-only changes alongside minor runtime fixes
• Documentation or JSDoc updates

Check for major bump signals:

• Removed or renamed exports in package.js
• Changed function signatures (new required parameters, changed return types)
• Removed public methods from classes
• Behavior changes that could break existing user code

Presenting the Decision

When proposing version bumps to the user, always present a table with the reason for each bump decision:

| Package | Current | Bump | New Version | Reason |
|---------|---------|------|-------------|--------|
| roles | 1.0.2 | minor | 1.1.0-betaXXX.0 | **New public API:** `getUserIdsInRoleAsync` added |
| webapp | 2.1.1 | patch | 2.1.2-betaXXX.0 | Removed Vary header — bug fix, no new APIs |
| google-config-ui | 1.0.4 | minor | 1.1.0-betaXXX.0 | **UI content change:** OAuth setup instructions updated — user-facing HTML differs |
| ddp-client | 3.1.1 | minor | 3.2.0-betaXXX.0 | **Removed internal method:** `_processOneDataMessage` — could break monkey-patching |

Always get user confirmation before applying the bumps.

Build Plugin Cascading Rule

When a package in the build plugin chain is bumped, its dependent build plugins must also be bumped — even if they have no code changes. This is because build plugins compile user code, and a change in an upstream compiler dependency can affect the compiled output.

The build plugin chain:

babel-compiler
├── ecmascript      (registerBuildPlugin, uses babel-compiler)
├── typescript       (registerBuildPlugin, uses babel-compiler)
└── minifier-js      (registerBuildPlugin, uses babel-compiler)

Rule: If babel-compiler is in the bump list, also bump ecmascript, typescript, and minifier-js. Cascade bumps must match or exceed the upstream magnitude — if babel-compiler gets a minor bump, cascading packages also get minor (unless their own changes warrant major).

This rule applies only to build plugin dependencies (registerBuildPlugin + api.use of the upstream package). It does not apply to:

• Umbrella/wrapper packages that api.imply a bumped package (e.g., ddp implying ddp-server)
• The accounts-* family that implies accounts-base
• Packages that only use a bumped package at runtime via api.use

When presenting the bump table, mark cascading bumps clearly:

| Package | Current | Bump | New Version | Reason |
|---------|---------|------|-------------|--------|
| babel-compiler | 7.13.0 | patch | 7.13.1-betaXXX.0 | Bug fix in compilation |
| typescript | 5.9.3 | patch | 5.9.4-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |
| ecmascript | 0.17.0 | patch | 0.17.1-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |
| minifier-js | 3.1.0 | patch | 3.1.1-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |

Files Touched Per Release Type

Preferred Approach: AI-Driven Analysis

Claude should perform the version bump process directly rather than relying on the update-semver script. The AI approach is preferred because:

1. Magnitude decisions require context — the script defaults everything to patch, missing minor/major bumps for new APIs or breaking changes
2. Branch name dependency — the script requires being on a release-* branch and will fail on preparation branches
3. Incomplete coverage — the script only handles packages/*/package.js, not release files, .meteor/versions, npm installer, or docs
4. Transparency — AI analysis shows reasoning for each bump decision, making review easier

AI Workflow

1. Detect changed packages: git diff devel --dirstat=files -- ./packages/
2. If modern-tool npm package code or dependency versions changed, complete its bump analysis and sync-modern-tool-versions
3. For each package, read the diff and current version from package.js
4. Classify the bump magnitude (patch/minor/major) based on change analysis
5. Present the full table with reasons to the user for confirmation
6. Apply all package.js version edits
7. Handle the manual files (release JSON, .meteor/versions, etc.)

Deriving the Version

Given a current stable version and the release branch track number:

• Patch bump beta: X.Y.Z → X.Y.(Z+1)-beta<TRACK>.0
• Minor bump beta: X.Y.Z → X.(Y+1).0-beta<TRACK>.0
• Major bump beta: X.Y.Z → (X+1).0.0-beta<TRACK>.0
• meteor-tool: same logic but suffix is -beta.0 (no track number)

Fallback: update-semver Script

Located at scripts/admin/update-semver/. Use only when on a release-* branch and a quick default-patch bump is acceptable.

Limitations:

• Requires release-* branch name (fails on other branches)
• Defaults all packages to patch (no magnitude analysis)
• Only updates packages/*/package.js — does not touch release files, .meteor/versions, npm installer, or docs

Usage

cd scripts/admin/update-semver

# Auto-bump all changed packages for beta (all patch)
npm run bump-experimental-beta

# Auto-bump all changed packages for RC
npm run bump-experimental-rc

# Bump specific packages with specific magnitudes
node index.js accounts-password.minor babel-compiler.minor

Release Type: Beta

Step 1: Analyze and bump package versions

1. Detect changed packages: git diff devel --dirstat=files -- ./packages/
2. For each changed package, analyze the diff to determine patch/minor/major
3. Present the bump table with reasons to the user
4. After confirmation, edit each packages/*/package.js Package.describe version
5. Apply the correct beta suffix: X.Y.Z-beta<TRACK>.0 for packages, X.Y.Z-beta.0 for meteor-tool

Step 2: Update experimental release file

Edit scripts/admin/meteor-release-experimental.json:

{
  "track": "METEOR",
  "version": "X.Y-beta.N",
  "recommended": false,
  "official": false,
  "description": "Meteor experimental release"
}

• Version format: X.Y-beta.N (short form, no patch component)
• Both recommended and official are false

Step 3: Update .meteor/versions in test apps

Only update test apps under test-apps/ (e.g., test-apps/34app/). Do NOT update .meteor/versions in tools/tests/apps/ or tools/e2e-tests/apps/ — those are pinned for CI stability.

find test-apps/ -name "versions" -path "*/.meteor/*"

In each file, update only packages that are at prerelease versions (or newly added packages). Leave already-stable package versions untouched.

Note: The set of packages at prerelease versions can grow between beta and RC as more changes are merged to the release branch.

Step 4: Update documentation and changelog

Use the changelog skill to create or update the changelog entry at v3-docs/docs/generators/changelog/versions/<VERSION>.md.

Update the version header date to the current date. Update the Bumped Meteor Packages section in the changelog with all packages that were bumped. Use the version that matches the current release stage — beta versions for beta releases, RC versions for RC releases, and final versions (no prerelease suffix) for official releases. Format: one package per line, name@version. Include meteor-tool@<version> when applicable.

Update any documentation files that reference specific package versions (e.g., rspack installation commands).

Release Type: RC (Release Candidate)

Step 1: Bump package versions

Update the prerelease suffix in each packages/*/package.js from beta to RC (or increment RC):

The transitions are:

• beta<TRACK>.N -> rc<TRACK>.0 (first RC)
• rc<TRACK>.N -> rc<TRACK>.N+1 (subsequent RCs)
• beta.N -> rc.0 (meteor-tool, first RC)
• rc.N -> rc.N+1 (meteor-tool, subsequent RCs)

Step 2: Update experimental release file

Edit scripts/admin/meteor-release-experimental.json:

{
  "track": "METEOR",
  "version": "X.Y-rc.N",
  "recommended": false,
  "official": false,
  "description": "Meteor experimental release"
}

Step 3: Update .meteor/versions in test apps

Same rule as beta: only test-apps/, not tools/tests/apps/ or tools/e2e-tests/apps/. Update only packages at prerelease versions.

Step 4: Update documentation and changelog

Update the version header date to the current date. Update changelog and any docs referencing RC versions. Update the Bumped Meteor Packages section with the current RC versions.

Release Type: Official

Official releases follow a two-step process (typically two separate commits).

Commit 1: Packages and release config

Step 1: Strip prerelease suffixes from all packages

For every packages/*/package.js that has an RC version, remove the -rc<TRACK>.N or -rc.N suffix:

• 3.2.0-rc340.4 -> 3.2.0
• 3.4.0-rc.4 -> 3.4.0 (meteor-tool)

Step 2: Update official release file

Edit scripts/admin/meteor-release-official.json:

{
  "track": "METEOR",
  "version": "X.Y",
  "recommended": false,
  "official": true,
  "description": "The Official Meteor Distribution"
}

• For .0 releases: short form X.Y (e.g., 3.4)
• For patch releases: X.Y.Z (e.g., 3.4.1)
• official must be true

Step 3: Update .meteor/versions in test apps

Only test-apps/, not tools/tests/apps/ or tools/e2e-tests/apps/. Strip prerelease suffixes from packages that were at RC versions. Leave stable versions untouched.

Step 4: Update changelog and docs

• Set the release date in the changelog
• Replace all RC version references with final versions
• Update the Bumped Meteor Packages section with final versions (no prerelease suffixes)
• Update v3-docs/docs/history.md with the full release entry

Commit 2: npm installer, required final gate

Prepare a separate installer commit after the packages commit. The official release is incomplete until these values agree:

Regenerate the lockfile from npm-packages/meteor-installer/:

npm install --package-lock-only --ignore-scripts
node ../../.github/skills/version-bump/scripts/audit-meteor-installer-version.mjs

Do not publish the meteor npm package or complete the official release while the audit fails. Published npm versions are immutable, so this cannot be fixed by republishing the same version.

Checklist

Beta Release

• Detect changed packages (git diff devel --dirstat=files -- ./packages/)
• Analyze each package diff and determine bump magnitude (patch/minor/major)
• Present bump table with reasons to user and get confirmation
• Apply version bumps to all packages/*/package.js
• Update scripts/admin/meteor-release-experimental.json version to X.Y.Z-beta.N
• Update .meteor/versions in test-apps/ only (not tools/tests/apps/ or tools/e2e-tests/apps/)
• Update changelog at v3-docs/docs/generators/changelog/versions/
• Update docs referencing package versions
• If modern-tool npm package code or dependency versions changed, complete its bump analysis and sync-modern-tool-versions; resolve audit failures

RC Release

• Update prerelease suffix from beta to RC (or increment RC) in all packages/*/package.js
• Update scripts/admin/meteor-release-experimental.json version to X.Y.Z-rc.N
• Update .meteor/versions in test-apps/ only (not tools/tests/apps/ or tools/e2e-tests/apps/)
• Update changelog
• Update docs referencing package versions
• If modern-tool npm package code or dependency versions changed, complete its bump analysis and sync-modern-tool-versions; resolve audit failures

Official Release

• Strip RC suffixes from all packages/*/package.js
• Update scripts/admin/meteor-release-official.json (version X.Y, official: true)
• Update .meteor/versions in test-apps/ only (strip prerelease suffixes)
• Finalize changelog (set date, replace RC versions with final)
• Update v3-docs/docs/history.md
• If modern-tool npm package code or dependency versions changed, complete its bump analysis and sync-modern-tool-versions; resolve audit failures
• Required separate installer commit: Synchronize config, package, and lockfile versions; pass audit-meteor-installer-version.mjs