From 5a95ac1e799528c8fe10e66135db7fb5cc793b6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nacho=20Codo=C3=B1er?= Date: Tue, 31 Mar 2026 17:19:40 +0200 Subject: [PATCH] add release process guidelines and detailed steps for beta, RC, and official releases --- DEVELOPMENT.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 39ecd8a849..75df87b1c9 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -286,3 +286,95 @@ Good commit messages are very important and you should make sure to explain what * A commit description which clearly explains the change if it's not super-obvious by the title. Some description always helps! * Reference related issues and pull-requests by number in the description body (e.g. "#9999"). * Add "Fixes" before the issue number if the addition of that commit fully resolves the issue. + +## Release Process + +Meteor releases follow a lifecycle: **beta** -> **RC (release candidate)** -> **official**. Releases are prepared on `release-` branches (e.g., `release-3.4.1`) and compared against the `devel` branch. + +Three AI skills support this process. They are defined as markdown files under `.github/skills/` and can be used by any AI coding assistant that supports reading project context. Trigger them from any session on a release branch. + +### AI Skills for Releases + +| Skill | Purpose | Skill File | +|-------|---------|------------| +| [changelog](.github/skills/changelog/SKILL.md) | Generate and update changelog entries from merged PRs | `v3-docs/docs/generators/changelog/versions/` | +| [version-bump](.github/skills/version-bump/SKILL.md) | Bump package versions for beta, RC, or official releases | `packages/*/package.js`, release config files | +| [docs-gap](.github/skills/docs-gap/SKILL.md) | Identify missing user-facing documentation for release changes | Produces a gap report in `docs/plans/` | + +### Preparing a Beta Release + +A beta is the first prerelease for a new version. It bumps all changed packages with a `-betaXXX.0` suffix. + +**Step 1 — Update the changelog:** + +``` +Update the changelog for 3.4.1 from the current branch compared to devel. +Check all merged PRs and complete with the missing fixes and features. +``` + +**Step 2 — Bump versions:** + +``` +Apply the version-bump skill for a beta.0 release on this branch against devel. +``` + +Claude will analyze each changed package, determine patch vs minor bumps based on the diff, present a table with reasons, and apply after confirmation. + +**Step 3 — Check for documentation gaps:** + +``` +Run the docs-gap skill to analyze what documentation is missing for this release. +``` + +### Preparing an RC Release + +An RC transitions beta versions to release candidate. The base version stays the same, only the suffix changes. + +**Step 1 — Update the changelog** (same as beta, catches any new PRs merged since the last beta). + +**Step 2 — Bump versions:** + +``` +Apply the version-bump skill to move from beta to RC on this branch. +``` + +### Preparing an Official Release + +An official release strips all prerelease suffixes and updates the release config and npm installer. + +**Step 1 — Finalize the changelog:** + +``` +Finalize the changelog for 3.4.1 — set the release date and replace any +RC version references with final versions. +``` + +**Step 2 — Bump versions:** + +``` +Apply the version-bump skill for an official release on this branch. +``` + +This is a two-commit process: packages and release config first, npm installer second. + +**Step 3 — Verify documentation coverage:** + +``` +Run the docs-gap skill and apply any missing documentation for this release. +``` + +### Other Useful Prompts + +``` +# Separate Rspack improvements from other changes in the changelog +Update the changelog separating Rspack improvements from other contributions. + +# Override a specific package bump magnitude +The roles package should be a minor bump because it adds getUserIdsInRoleAsync. + +# Generate the gap report without applying fixes +Run the docs-gap skill to produce a gap report only — don't write any docs yet. + +# Check which packages changed vs devel +What packages have changed on this branch compared to devel? +```