chore(release): publish release-v14 under its own dist-tag

.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": [

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
+                                   ...
 ```

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,29 +9,43 @@ 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
 
 At the moment these manual actions have to be taken to achieve a successful release:
 
 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: <reason>` 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: <reason>` 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