| name | version-bump |
| description | Use when bumping Meteor package versions for beta, RC, or official releases. Covers the two version schemes (meteor-tool vs all other packages), the update-semver automation tool, manual files the tool does not handle, and the full lifecycle from beta through official release. Applies to packages/*/package.js, scripts/admin/, npm-packages/meteor-installer/, and .meteor/versions in test apps. |
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):
| Branch | Track Number |
|---|
release-3.4 | 340 |
release-3.4.1 | 341 |
release-3.5 | 350 |
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:
- You must be on a
release-* branch
- All changes intended for the release must be merged
- Confirm the release type with the user: beta, RC, or official
Version Format Reference
Two Distinct Schemes
1. meteor-tool — simple semver prerelease (no track number):
| Stage | Format | Example |
|---|
| Beta | X.Y.Z-beta.N | 3.4.0-beta.0 |
| RC | X.Y.Z-rc.N | 3.4.0-rc.0 |
| Official | X.Y.Z | 3.4.0 |
2. All other packages — encode the track number in the prerelease tag:
| Stage | Format | Example (track 340) |
|---|
| Beta | X.Y.Z-beta<TRACK>.N | 3.2.0-beta340.0 |
| RC | X.Y.Z-rc<TRACK>.N | 3.2.0-rc340.0 |
| Official | X.Y.Z | 3.2.0 |
Version Transitions
| Transition | meteor-tool | Other packages |
|---|
| Stable to first beta | 3.3.1 -> 3.4.0-beta.0 | 3.1.2 -> 3.2.0-beta340.0 |
| Beta to next beta | 3.4.0-beta.0 -> 3.4.0-beta.1 | 3.2.0-beta340.0 -> 3.2.0-beta340.1 |
| Beta to first RC | 3.4.0-beta.14 -> 3.4.0-rc.0 | 3.2.0-beta340.14 -> 3.2.0-rc340.0 |
| RC to next RC | 3.4.0-rc.0 -> 3.4.0-rc.1 | 3.2.0-rc340.0 -> 3.2.0-rc340.1 |
| RC to official | 3.4.0-rc.4 -> 3.4.0 | 3.2.0-rc340.4 -> 3.2.0 |
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
| Magnitude | When to use | Examples |
|---|
| Patch | Bug fixes, performance improvements, type fixes, internal refactors with no API changes | Fix passwordValidator precedence, remove redundant await, TypeScript type corrections |
| Minor | New public APIs, new exported functions/methods, new user-facing features or capabilities | New getUserIdsInRoleAsync method, new CSS auto-delegation feature, new test assertion methods |
| Major | Breaking changes, removed APIs, renamed exports, changed function signatures | Removed public method, renamed package export, async migration of sync API |
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
| File | Beta | RC | Official |
|---|
packages/*/package.js | Yes | Yes | Yes |
scripts/admin/meteor-release-experimental.json | Yes | Yes | No |
scripts/admin/meteor-release-official.json | No | No | Yes |
.meteor/versions in test-apps/ only | Yes | Yes | Yes |
npm-packages/meteor-installer/config.js | No | No | Yes |
npm-packages/meteor-installer/package.json + lock | No | No | Yes |
v3-docs/ (changelog, docs with version refs) | Yes | Yes | Yes |
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:
- Magnitude decisions require context — the script defaults everything to patch, missing minor/major bumps for new APIs or breaking changes
- Branch name dependency — the script requires being on a
release-* branch and will fail on preparation branches
- Incomplete coverage — the script only handles
packages/*/package.js, not release files, .meteor/versions, npm installer, or docs
- Transparency — AI analysis shows reasoning for each bump decision, making review easier
AI Workflow
- Detect changed packages:
git diff devel --dirstat=files -- ./packages/
- For each package, read the diff and current version from
package.js
- Classify the bump magnitude (patch/minor/major) based on change analysis
- Present the full table with reasons to the user for confirmation
- Apply all
package.js version edits
- 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
npm run bump-experimental-beta
npm run bump-experimental-rc
node index.js accounts-password.minor babel-compiler.minor
Release Type: Beta
Step 1: Analyze and bump package versions
- Detect changed packages:
git diff devel --dirstat=files -- ./packages/
- For each changed package, analyze the diff to determine patch/minor/major
- Present the bump table with reasons to the user
- After confirmation, edit each
packages/*/package.js Package.describe version
- 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.03.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
This is a separate commit after the packages commit.
Step 1: Update installer config
Edit npm-packages/meteor-installer/config.js:
const METEOR_LATEST_VERSION = 'X.Y';
- For
.0 releases: short form without patch (e.g., '3.4')
- For patch releases: full version (e.g.,
'3.4.1', '3.3.2')
Step 2: Update installer package.json
Edit npm-packages/meteor-installer/package.json:
{
"version": "X.Y.Z"
}
Full semver form required by npm (e.g., "3.4.0", "3.4.1").
Step 3: Update package-lock.json
Run npm install in npm-packages/meteor-installer/ to regenerate the lock file, or manually update the version field.
Checklist
Beta Release
RC Release
Official Release
