From 34e78847011a3de136cf8278005d37b8bbde5bd3 Mon Sep 17 00:00:00 2001 From: martincupela Date: Fri, 6 Nov 2026 16:29:15 +0100 Subject: [PATCH] chore(release): publish release-v14 under its own dist-tag release-v14 becomes the v14 maintenance line, like release-v13 and release-v12: channel v14, range 14.x, npm dist-tag release-v14. master publishes v15 under latest. Merge this before 15.0.0 is released, so no later v14 release can move latest. Ticket: REACT-1532 --- .releaserc.json | 8 ++++---- developers/BRANCHES.md | 24 +++++++++++++++++++----- developers/RELEASE.md | 32 +++++++++++++++++++++++--------- 3 files changed, 46 insertions(+), 18 deletions(-) diff --git a/.releaserc.json b/.releaserc.json index e6439d3a75..9e33978923 100644 --- a/.releaserc.json +++ b/.releaserc.json @@ -1,13 +1,13 @@ { "branches": [ { - "name": "release-v14", + "name": "master", "channel": "latest" }, { - "name": "master", - "prerelease": "rc", - "channel": "rc" + "name": "release-v14", + "channel": "v14", + "range": "14.x" } ], "plugins": [ diff --git a/developers/BRANCHES.md b/developers/BRANCHES.md index 4c5f6bbdb7..06aee03fdd 100644 --- a/developers/BRANCHES.md +++ b/developers/BRANCHES.md @@ -1,12 +1,26 @@ # Branches -We have one (base) branch, `master`. If you want to implement a solution, you are required to create branches from `master` or its derivatives. The `master` branch serves for release and should receive updates only through squash-merging feature branches - each of these squashed-commits should be up to date with `master` branch and should be passing CI requirements. +We have two base branches: + +- `master` — the v15 line. Releases from it are published under the npm `latest` tag. +- `release-v14` — the v14 maintenance line. Releases from it are published under the npm `release-v14` tag (`npm install stream-chat-react@release-v14`). + +Older lines (`release-v13`, `release-v12`, …) are maintenance branches as well, published under the npm `release-v13`, `release-v12`, … tags. + +If you want to implement a solution, create a branch from the base branch it belongs to: `master` for v15 work, `release-v14` for a v14 fix. A base branch should receive updates only through squash-merging feature branches - each of these squashed commits should be up to date with its base branch and should be passing CI requirements. + +A fix that applies to both lines is merged into `release-v14` and ported to `master`. + +`release-v14` accepts only 14.x releases and must not receive breaking changes. It is a maintenance branch in `.releaserc.json` (`"range": "14.x"`), so semantic-release refuses a release that would leave 14.x: a `fix:` or `feat:` commit with a `BREAKING CHANGE:` footer makes the release fail with `EINVALIDNEXTVERSION` instead of publishing v15. Its commit analyzer uses the `angular` preset, which does not read `!` in a header, so a `fix!:` commit on `release-v14` releases nothing. + +A breaking change on `master` releases the next major (16.0.0) under `latest`. Mark a commit on `master` as breaking only when the next major is planned. The branch architecture in this repository is as follows: ```shell -NPM <--- master <--- branch_solution_x - <--- branch_solution_y - <--- branch_solution_x - ... +NPM (latest) <--- master <--- branch_solution_x + <--- branch_solution_y + ... +NPM (release-v14) <--- release-v14 <--- branch_fix_x + ... ``` diff --git a/developers/RELEASE.md b/developers/RELEASE.md index 8ef382b5da..6f617fcd8e 100644 --- a/developers/RELEASE.md +++ b/developers/RELEASE.md @@ -1,4 +1,4 @@ -# Release process (for package and documentation) +# Release process The `stream-chat-react` package follows semantic versioning and the release is to a big part automated by `semantic-release`. The utility automates: @@ -9,13 +9,29 @@ The `stream-chat-react` package follows semantic versioning and the release is t In order to get the above generated outputs, each contributor should follow [Angular's Commit Message Format rules](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). +## Branches and npm dist-tags + +The Release workflow runs `semantic-release` on the branch you pick, so that branch's own `.releaserc.json` decides where its releases go. `master` and `release-v14` keep the same `branches` list: + +| Branch | Entry in `branches` | Versions | npm dist-tag | +| ------------- | -------------------------------------------------------------- | -------- | ------------- | +| `master` | `{ "name": "master", "channel": "latest" }` | 15.x | `latest` | +| `release-v14` | `{ "name": "release-v14", "channel": "v14", "range": "14.x" }` | 14.x | `release-v14` | + +`@semantic-release/npm` publishes a release under its channel as the dist-tag, and prefixes a channel that reads as a version range with `release-`: the `v14` channel publishes under `release-v14`. Older maintenance branches work the same way (`release-v13` publishes under `release-v13`). + +A maintenance branch only publishes versions inside its `range`. If its commits call for a version outside it, for example 15.0.0 from a breaking change on `release-v14`, the release fails with `EINVALIDNEXTVERSION` and nothing is published. + ## Major version release preparations -We need to: +While the next major is in prerelease, `master` is a prerelease branch, for example `{ "name": "master", "prerelease": "rc", "channel": "rc" }`, and the previous line's branch (for example `release-v14`) is the release branch on `latest`. When the major goes GA: -1. Convert the current latest branch to a version branch by creating a PR with adjusted `.releaserc.json`. Example PR: https://github.com/GetStream/stream-chat-react/pull/2507 +1. Make the previous line a maintenance branch. On that branch, set the `branches` list in `.releaserc.json` to `master` on `latest` plus the branch with its own channel and range, as in the table above. Merge this first: once it is in, a release from that branch can no longer move `latest`. Example PR: https://github.com/GetStream/stream-chat-react/pull/3122 +2. On `master`, replace the prerelease entry with `{ "name": "master", "channel": "latest" }` and list the maintenance branch next to it, the same list as in step 1. Example PR: https://github.com/GetStream/stream-chat-react/pull/3121 +3. Run the Release workflow on `master`, with a dry run first. A release branch ignores the `-rc.N` tags, so `semantic-release` compares `master` with its last stable tag. The breaking commits since then make the release `X.0.0`, published under `latest`. No extra commit is needed. +4. Run the Release workflow on the maintenance branch once, at any time after step 1. With no new fixes it only adds the branch's last version to the branch's dist-tag (for example `14.16.1` to `release-v14`), so `npm install stream-chat-react@release-v14` works before the first maintenance release. The workflow publishes through npm trusted publishing (OIDC). If this step fails with `E401` on `npm dist-tag`, the package's trusted publisher settings on npmjs.com do not allow `npm dist-tag`: allow it, or add the tag by hand with `npm dist-tag add stream-chat-react@14.16.1 release-v14`. A re-run does not retry the step. -2. Configure the `master` branch back from `prerelease` to `latest` and add a config for the next version branch also designated as `latest`. Example PR: https://github.com/GetStream/stream-chat-react/pull/2506. +If step 3 runs before step 1, the next release from the previous line's branch publishes under `latest` and replaces the new major there. ## Required steps @@ -23,15 +39,13 @@ At the moment these manual actions have to be taken to achieve a successful rele 1. make sure that all the new required features and bug fixes in peer dependency repositories `@stream-io/stream-chat-css` and `stream-chat-js` are released 2. make sure that the peer dependencies `@stream-io/stream-chat-css` and `stream-chat-js` are installed at their latest version (see `package.json`, `yarn.lock`) (if applicable) -3. squash-merge required pull requests to `master` branch with appropriate message name, for example: `fix(scope): new feature`, if this feature is breaking, make sure to include `BREAKING CHANGE: ` in the message footer +3. squash-merge required pull requests to their base branch (`master` or `release-v14`) with appropriate message name, for example: `fix(scope): new feature`. A breaking change (`!` or a `BREAKING CHANGE: ` footer) releases a new major from `master`, so merge one only when the next major is planned (see `developers/BRANCHES.md`) 4. navigate to ["Actions"](https://github.com/GetStream/stream-chat-react/actions) and in the left bar select the "Release" workflow -5. click "Run workflow" and select the branch you want to release from then adjust the prompt options and click "Run workflow", note that allowed branches for **PACKAGE RELEASE** are: branch names starting with `release` and `master`, there _is no such limititation_ for the **DOCUMENTATION RELEASE**, extend the workflow condition and `.releaserc.json` as needed. The `master` branch is the release-candidate branch. +5. click "Run workflow" and select the branch you want to release from then adjust the prompt options and click "Run workflow", note that allowed branches are branch names starting with `release`, `rc` and `master` (a dry run can use any branch), extend the workflow condition and `.releaserc.json` as needed. Releases from `master` go to `latest`, releases from `release-v14` to `release-v14` (see [Branches and npm dist-tags](#branches-and-npm-dist-tags)). ## Available release prompt options -- `docs_only` option if checked will skip the `package_release` job and will only run the `docs_release` -- `dry_run` option if checked will run the `semantic-release` command in ["dry run" mode](https://semantic-release.gitbook.io/semantic-release/usage/configuration#dryrun) and will skip `docs_release` -- `docs_env` (required) option offers two environment options to which the documentation will be pushed to via `GetStream/push-stream-chat-docusaurus-action` - defaults to `staging` +- `dry_run` option if checked will run the `semantic-release` command in ["dry run" mode](https://semantic-release.gitbook.io/semantic-release/usage/configuration#dryrun) ## After the release