Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: How to release changes to older minors #29534

Merged
merged 4 commits into from
Nov 5, 2024
Merged

Documentation: How to release changes to older minors #29534

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ef5bde7
add section about relesing changes to older minor versions
JReinhold Nov 4, 2024
c7ee4a6
fix typo
JReinhold Nov 4, 2024
9cec767
Apply suggestions from code review
JReinhold Nov 5, 2024
27191fd
fix nested lists
JReinhold Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions CONTRIBUTING/RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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 <CURRENT_VERSION> to <NEXT_VERSION> MANUALLY"`
10. Add a new entry to `CHANGELOG.md`, describing your changes
11. Commit with `git commit -m "Update CHANGELOG.md with <NEXT_VERSION> 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=<NPM_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<VERSION>` (e.g., `v8.3.7`)
2. Target: your branch (e.g., `patch-8-3-7`)
3. Previous tag: `v<PREVIOUS_VERSION>` (e.g., `v8.3.6`)
4. Title: `v<VERSION>` (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.
Expand Down