version-bump

# 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 ```bash 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: | Stage | Target on the required `X.Y.Z` line | |-------|--------------------------------------| | Beta | Start at `X.Y.Z-beta.0`; preserve an existing `beta.N` or later stage | | RC | Move beta to `X.Y.Z-rc.0`; preserve an existing `rc.N` or stable version | | Official | Use `X.Y.Z` without a prerelease suffix | 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](../sync-modern-tool-versions/SKILL.md) 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): | 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: ```bash 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: ```markdown | 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: ```markdown | 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: 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