diff --git a/CONTRIBUTING/RELEASING.md b/CONTRIBUTING/RELEASING.md index afc1bc377451..33a74bfdc224 100644 --- a/CONTRIBUTING/RELEASING.md +++ b/CONTRIBUTING/RELEASING.md @@ -19,6 +19,7 @@ - [5. Make Manual Changes](#5-make-manual-changes) - [6. Merge](#6-merge) - [7. See the "Publish" Workflow Finish](#7-see-the-publish-workflow-finish) +- [Releasing changes to older minor versions](#releasing-changes-to-older-minor-versions) - [Releasing Locally in an Emergency 🚨](#releasing-locally-in-an-emergency-) - [Canary Releases](#canary-releases) - [With GitHub UI](#with-github-ui) @@ -330,6 +331,59 @@ Merging the pull request will trigger [the publish workflow](https://github.com/ Done! 🚀 +## Releasing changes to older minor versions + +If you need to release a change to an older minor version that is not the latest, you have to do it manually, locally. The process is described below, with an example of releasing a new `v8.3.7` in a situation where `8.4.0` is currently the latest version. + +1. Checkout the _existing_ tag that matches the latest minor release you want to bump, and create a new branch from it. In this case, we want to do: + 1. `git fetch --all --tags` + 2. `git checkout tags/v8.3.6 -b patch-8-3-7` +2. Make the changes you need to, most likely cherry-picking commits from the fix you need to back-port. +3. Run `yarn install` in `scripts` and `code` +4. Build all packages in `code` with `yarn task --task compile --no-link` +5. Commit and push your changes. +6. Trigger _daily_ CI manually on your branch: + 1. Open [CircleCI](https://app.circleci.com/pipelines/github/storybookjs/storybook) and click "Trigger Pipeline" on the top right corner of the page. + 2. Set the following configuration options: + - Pipeline: _"storybook default"_ + - Config Source: _"storybook"_ + - Branch: Your branch, eg. `patch-8-3-7` + 3. Add a parameter, with _"name"_ `workflow`, _"value"_ `daily` +7. Wait for CI to finish successfully. +8. Bump all package versions: + 1. `cd scripts` + 2. `yarn release:version --release-type patch` +9. Commit with `git commit -m "Bump version from to MANUALLY"` +10. Add a new entry to `CHANGELOG.md`, describing your changes +11. Commit with `git commit -m "Update CHANGELOG.md with MANUALLY"` +12. Ensure you have the correct write permissions for all the Storybook npm packages. You need to be an admin of the _storybook_ org, and the packages that are not in the org. The simplest way to check this is to ensure you can see the _"Settings"_ tab in the following packages: + 1. [`@storybook/react-vite`](https://www.npmjs.com/package/@storybook/react-vite/access) + 2. [`storybook`](https://www.npmjs.com/package/storybook/access) + 3. [`sb`](https://www.npmjs.com/package/sb/access) + 4. [`create-storybook`](https://www.npmjs.com/package/create-storybook/access) +13. Get your npm access token or generate a new one at https://www.npmjs.com/settings/your-username/tokens. Remember to give it access to the `storybook` org and the packages not in the org, as listed above. +14. Publish all packages with `YARN_NPM_AUTH_TOKEN= yarn release:publish --tag tag-for-publishing-older-releases --verbose` + - It goes through all packages and publishes them. If any number of packages fails to publish, it will retry 5 times, skipping those that have already been published. +15. Confirm the new version has been released on npm with the tag `tag-for-publishing-older-releases`: + 1. [`@storybook/react-vite`](https://www.npmjs.com/package/@storybook/react-vite?activeTab=versions) + 2. [`storybook`](https://www.npmjs.com/package/storybook?activeTab=versions) + 3. [`sb`](https://www.npmjs.com/package/sb?activeTab=versions) + 4. [`create-storybook`](https://www.npmjs.com/package/create-storybook?activeTab=versions) +16. Push +17. Manually create a GitHub Release at https://github.com/storybookjs/storybook/releases/new with: + 1. Create new tag: `v` (e.g., `v8.3.7`) + 2. Target: your branch (e.g., `patch-8-3-7`) + 3. Previous tag: `v` (e.g., `v8.3.6`) + 4. Title: `v` (e.g., `v8.3.7`) + 5. Description: The content you added to `CHANGELOG.md` + 6. Untick _"Set as the latest release"_ +18. Cherry-pick your changelog changes into `next`, so they are actually visible + 1. Checkout the `next` branch + 2. Cherry-pick the commit you created with your changelog modifications + 3. Push + +Done. 🎉 + ## Releasing Locally in an Emergency 🚨 Things can fail, code can break, and bugs can exist. When automation is broken, there may be a need for an emergency escape hatch to release new fixes. In such a situation, it's valid to run the whole release process locally instead of relying on pull requests and workflows. You don't need to create pull requests or split preparation and publishing; you can do it all at once, but make sure you still follow the correct branching strategy.