[RFC] Upgrade Release Process

[JReinhold]

Status: accepted

Tracked in: #22532

Summary

This is a proposal to revamp the way we do and handle releases in the Storybook monorepo. This doesn’t have an affect on the regular Storybook user, it only affects maintainers and contributors to the Storybook core monorepo.

Problem Statement

• Making new releases of the core Storybook packages is currently a black box to most. As it stands, only one person on the team can cut new releases of Storybook. This creates a low bus factor — a high risk that releases cannot be done should something go wrong. This can also delay releasing a new version due to timezone or availability issues.
• There’s no setup for “canary” or “staging” releases. There’s no easy way to test out code in a separate project (like in a satellite repo) without waiting for a new release. Canary releases for PRs would allow anyone to just change the Storybook version in their project to the PR’s canary version to test it out. This makes it easy to test a PR with a completely separate project or Storybook package, by changing the version specifier to point at the canary release.

Non-goals

• Ideas have been floating around about how packages are versioned collectively and independently. That is not a goal in this project proposal. This project should maintain the current versioning strategy (except for canaries).

• This proposal also doesn’t concern any of the Storybook satellite repositories, only the monorepo. If this is successful we could consider streamlining the workflow and implementing it in the satellite repos, but that is for another project.

• Scheduling and the cadence of releases are also not part of this proposal. However this proposal is about getting the tooling right, so whatever tooling solution we land on, it should support changing our release process/schedule/cadence later down the road without too much work needed.

High level process

There are five types of releases that will be handled somewhat differently, but following the overall same principles. It will be based on automatically created and updated PRs, that can also be triggered manually.

Prereleases - 7.1.0-alpha.12 -> 7.1.0-alpha.13

These happen multiple times a week

1. A PR will automatically be opened from a fresh branch version-from-7.1.0-alpha.16 to next-release on every push to next. If the PR is already open, it will be kept up-to-date with description changes and force pushing commits. This process can also be manually triggered if needed.
2. The PR will consist of:
   1. Version bumps in all package.jsons and other files like versions.ts
   2. Changes to CHANGELOG.md generated as specced below
   3. Changes listed in the PR description, along with a checklist to go through manually
3. When we're ready to release, a Releaser will go through the check list:
   1. Freeze the PR by applying the "freeze" label on it, stopping any actions from modifying it further
   2. QA each PR that is part of the release:
      1. Is the changelog high quality - it's based on PR titles, which are usually bad.
      2. Change any PR titles necessary
      3. Check that each PR content is high quality, has it been tested, are we sure it's not a breaking change, etc.
      4. revert any bad PRs
   3. If necessary, manually trigger the workflow again, to reflect changes to PR titles and reverts (manual triggers should ignore the "freeze" label)
   4. Merge the PR to next-release
4. When the PR is merged, an action will:
   1. publish all packages
   2. create a GitHub Release
   3. tag the commit
   4. merge next-release back to next. If this causes a merge conflict, this will have to be done manually
5. ... the cycle starts over

Prerelease promotions - 7.1.0-alpha.13 -> 7.1.0-beta.0

These happen once every 1-2 months

Same process as above, except before merging, the Releaser manually triggers the Action with a "tag: beta" input, that will change versions from the proposed 7.1.0-alpha.14 to 7.1.0-beta.0.

Minor/major releases - 7.1.0-rc.2 -> 7.1.0

These happen once every quarter

Same process as above, except before merging, the Releaser manually triggers the Action with a "tag: stable" input, that will change versions from the proposed 7.1.0-rc.3 to 7.1.0. When the PR is merged, the action will do the usual publishing work, and force merge next into main. The following GitHub Action that triggers on a push to next will generate a release PR with 7.2.0-alpha.0, to start the cycle over.

Patch releases to stable - subset of 7.1.0-alpha.13 -> 7.0.14

These happen roughly every second week

This process is a bit different from the above because it needs to merge to the main branch and not next, but the principle is the same.

1. Any PR to next that needs to be patched back to stable, needs to have a "patch" label
2. On pushes to next, an action check for any such PRs with the "patch" label
3. It will create a release branch (version-from-7.0.11) and PR similar to the one for prereleases, except that it targets main.
4. Each "patch" PR that it finds it will attempt to cherry-pick to the version-from-7.0.11 branch
5. Sometimes it might cause merge conflicts, in which case the PR will be skipped
6. When all is done, the description for the release PR will contain a list of PRs that couldn't be cherry picked, for the Releaser to manually do that and solve any merge conflicts.
7. An important additional step for the Releaser is to check that all PRs are actually patches/fixes, and not new features, and that everything actually works, given that some cherry picked PRs could rely on functionality not yet found in stable.

When the PR has been merged to main-release by the Releaser, after the usual publishing steps, the action will also label all patched PRs with "picked" so they are ignored for the next patch release.

Patch releases to earlier versions - subset of 7.1.0-alpha.13 -> 6.5.14

These happen 2-3 times a year

Given that this happens so rarely on a case by case basis, I'm okay with this being a completely manual process. The only thing we then need to keep in mind, is that all these versioning and publishing scripts needs to be executable locally, outside of a GitHub Action.

Changelog format

• The changelog will be based on PR titles and labels, as they are today.
• It will ignore "documentation" and "build" PRs, as they are not user-facing
• They will contain links to the PR and the original author
• PR title is of format “[Area]: [Summary]”, e.g. “React: Fix hooks in CSF3 render functions”
  • Areas include: React, Vue, Core, Docs, Controls, etc.
  • First word of summary indicates the type: “Add”, “Fix”, “Upgrade”, etc.
  • The entire title should fit on a line (< 60 chars?)
• The PRs will be ungrouped and have the area be identified by the the title format per above, sorted by area. If we release often, these lists will typically be less than 10 PRs long, so grouping just makes it harder to parse.
• For minor/major releases, we typically write custom changelogs that highlight the main features of the release and point to more information (e.g. blog posts, etc.)

A GitHub release will have the same content as the changelog entry

The changelog will be split into a CHANGELOG.md and CHANGELOG.prerelease.md, along with the existing CHANGELOG.v6.md we have to day. This split makes it easy for users to see what has changed between 7.0.6 and 7.0.10 without having to sift through 15x 7.1.0 alpha releases. It's also easier to implement, as it allows us to just put new entries at the top, not worrying about trying to insert entries in the right order.

Low level implementation plan

It's important that this whole process can be done manually, locally as well, if for some reason we need an extra level of control. The automated GitHub Actions will be thin wrappers around those scripts, that also takes care of branches, committing and pushing, something you don't want to happen locally.

Scripts

1. check-release-needed.ts
   • Checks if a release is needed. It is NOT needed if all PRs are "documentation" or "build" PRs
2. version.ts
   • bumps all package versions
   • use arguments to set strategy
3. write-changelog.ts
   • retrieves all relevant PRs since last release
   • use arguments to specify if it should only look at "patch" PRs
   • writes a changelog entry to the the file.
4. generate-pr-description.ts
   • generates the PR description for the Release PR
   • not really useful locally, except for a todo list
   • Will generate a different kind of description if no versioning is necessary
5. pick-patches.ts
   • cherry picks patch PRs - similar to Build: Script to bulk cherry-pick patch PRs #22506
6. publish.ts
   • checks if packages needs publishing
   • publishes all packages (assuming their version has been bumped prior to this)
   • checks if it was successful
   • retrys unsuccessful packages

Action: Create Prerelease PR

This action will create and keep a release branch+PR up-to-date.

• Triggers: pushes to next and manual
• Inputs to workflow_dispatch: tag (alpha, beta, rc, stable)
• Abort early if an existing Release PR has "freeze" label
• Run check-release-needed.ts, verson.ts, write-changelog.ts
• Abort late if an existing Release PR has "freeze" label
• Create version-from-7.1.0-alpha.16 branch and force push
• Create or update existing PR pointing to next-release, with generate-pr-description.ts

Action: Create Patch Release PR

• Triggers: pushes to next and manual
• Abort early if an existing Release PR has "freeze" label
• Run check-release-needed.ts, verson.ts, write-changelog.ts, pick-patches.ts
• Abort late if an existing Release PR has "freeze" label
• Create version-from-7.0.10 branch and force push
• Create or update existing PR pointing to main, with generate-pr-description.ts

Action: Publish new prereleases

• Trigger: pushes to next-release
• Needs "release" GH environment to get access to NPM_TOKEN
• Core Team member needs to approve/review the run
• Run publish.ts if applicable
• Merge next-release to next
• If it's a stable release (eg. 7.1.0-rc.2 -> 7.1.0), merge next to main

Action: Publish patch releases

• Trigger: pushes to main-release
• Needs "release" GH environment to get access to NPM_TOKEN
• Core Team member needs to approve/review the run
• Run publish.ts if applicable
• Merge main-release to main

Deliverables

See task list in tracking issue #22532

Initial attempt - with Changesets. Cancelled

Here for historical reasons

Tracking Issue: #22242

---

The proposal here is to rely on the Changesets package - a very popular OSS tool to manage package releases, especially in monorepo setups.

While Changesets can do a lot of things, here’s a very quick summary of the moving parts and how the workflow would be for maintainers and contributors.

1. Work is done on a branch.
2. As part of that work, the contributor runs yarn changesets which prompts the user to specify changed packages, version bumps and a changelog summary. This creates a special file that is committed.
3. When a PR opens, a GitHub bot checks for changesets files. If none are present (because step 2 was skipped) it will ask if that is on purpose or by mistake with a comment on the PR.
4. The PR is merged.
5. A changesets GH Action will open a PR labeled “Version Packages” that contains all merged changes, and it will keep the PR up-to-date whenever new changes gets merged to next or main.
6. When that “Version Packages” PR is merged by a team member, a new version is released and published automatically.

Here’s a YouTube video quickly explaining most of a Changesets workflow:
https://youtu.be/eh89VE3Mk5g?t=84

Prior Art

Changesets is used by many of the other teams in the ecosystem:

• pnpm
• Preact
• Remix
• Emotion
• Shopify
• Verdaccio
• Lit
• GitHub Primer
• SvelteKit
• Astro
• …

Deliverables

1. A dummy repository with a similar structure as the Storybook monorepo, which implements the release setup.
   1. Multiple packages, scattered in different nested directories.
   2. A main release branch and a next prerelease branch.
2. Adding the Changesets CLI, GitHub bot and GitHub Action
3. Canary releases for each PR in the dummy repo
4. Define the setup and process needed to be able to backport fixes to previous minor and major releases
5. Define how to ensure only the core team can cut releases.
6. A video tour of the workflow from A-Z that clearly demonstrates how we work with it, to gather feedback on if we want to change the main workflow.
7. Move the implementation to the monorepo.
   1. Add Changesets CLI, configuration, bot, GitHub Action and anything else necessary to the monorepo with a PR to next.
   2. Remove all the bits that aren't necessary for releases anymore.
   3. Merge to next and hopefully see the "Version Packages" PR
   4. Merge the "Version Packages" PR and hopefully trigger a new 7.1.0-alpha version release.
8. Update Contribution documentation detailing the new workflow

Risks

• Anyone can release. With this setup, releases will happen whenever the “Version Packages” PR is merged to next/ main. This means that anyone with permission to merge to those branches can trigger a release. We want to ensure that only members of the core team can perform those merges.
• Releasing irreversible package versions as part of implementation. It’s almost impossible to unrelease versions from npm. We risk releasing a wrong version during this project implementation, worst case bumping Storybook to 8.0.0 without being able to reverse that. This should be mitigated by implementing all of this in a separate dummy repo before moving it over to the monorepo.

Unresolved Questions

• How do we release patches back to main if next is already on a prerelease of the upcoming version? Say a PR to next (which is at 7.1.0-alpha.8) fixes a bug, and we want to release that bug as well to 7.0.9, how do we do that?
• How exactly will the prerelease setup work, how do we manage alpha, beta, rc?
• How exactly will the canary setup work for each PR?
• Should the “Version Packages” PR be tested or not? It only updates changelogs and versions, so it would essentially be testing the same as the base branch, or the “ci:merged” label, thus redundant.
• What do we want to do with changelogs? Changesets create changelog files and GitHub releases, but it can be customized however we want, either disabling it completely, or something else. https://github.com/changesets/changesets/blob/main/docs/modifying-changelog-format.md

Alternatives considered / Abandoned Ideas

Keep the existing workflow. The problem statement of this proposal should describe why this is not recommended.

Make the current release tool usable by the whole core team. This would still fix some of the problems around the bus factor and spread out the responsibility of releasing to the rest of the team. But not using a tool battle-tested by the rest of the ecosystem would still mean that we have a higher maintenance burden. It would also require more effort to get a great experience (eg. using an existing GitHub bot that provides a good experience vs. building our own GitHub bot from scratch). Using a popular tool used by other similar projects also indicates that the tool gets new features more frequently, which we could potentially leverage without much effort.

Use Auto instead of Changesets. Auto is another automated packaging/releasing tool that is familiar to the Storybook team, and is used in quite a few of the satellite repos. But its support of publishing multiple packages in a monorepos is reliant on Lerna, a tool now semi-deprecated that we don’t really utilize.

[JReinhold]

The project and this RFC can now be considered "complete". The tracking issue at #22532 still has minor outstanding improvements, but overall the RFC is complete.