How to do a major release

A major release is different to minor/patch releases because it's important to keep documentation from older major releases available and possibly fix bugs on the older releases. To always be able to access old docs easily, each major version has it's own release branch in the form of release/v1. These branches deploy to different sites on netlify to ease updates. A redirect table on the main page redirects requests to the different older releases, for example https://design-system.post.ch/v1.

In order to create a new major release, the regular changeset workflow can be used. From v7, the most important packages synchronise their version number to ease understanding of versioning and make it easier to see which Design System packages work together.

Steps to deploy a new site for an old major release

Note: these steps can be taken before or after a new major release. Doing it before a major release has the benefit that the docs for the last major release are already online and available when the new major lands.

1. Create the regular changesets needed for a major release, don't merge the automatically created release PR yet (e.g. design-system-styles@7.0.0)
2. Find the latest release tag for the current major version (e.g. design-system-styles@6.6.3). Why not branch from the current main? The current main already contains breaking changes that will go to the next major version. These changes should not end up on the release branch, so the last safe commit is the last release.
3. From this tag, create a new release branch (e.g. release/v6)
4. On the release branch run pnpm bootstrap locally to create a complete build
5. On netlify, create a new site with manual deploys to host the old major docs (e.g. design-system-version-6). Upload the locally built documentation from the release branch as a first publish
6. On the release branch, update the .netlify/state.json
   • set siteId to the new site ID, e.g. 4164f5b5-7406-4692-ac27-d1fcb04b139c (netlify site ids are not private)
   • set siteName to the default netlify URL without protocol, e.g. design-system-version-6.netlify.app
7. On the release branch, update the .changeset/config.json so the baseBranch points to the release branch instead of main. This enables a release workflow where it's possible to branch from the release branch, fix a bug, create a changeset and merge back to release which will create an automated release PR specific to this release branch
8. To test the settings, create a changeset and merge it to the release branch. The release action should create an automated PR. When merging this PR to the release branch, the documentation should get published
9. On main, update the versions.json file to include information about the old major release
10. On main, update the redirects.json file to include a reference to the old major version site on netlify (e.g. https://design-system.post.ch/v6 points to design-system-version-6)
11. On main, continue with the release by merging the automatically created release PR. The packages should be published with the new major version number

Notes on automating the release process

There was an effort to automate the release process because most of these steps would be possible to do with an Action, but some of them are pretty difficult with the current (Spring 2024) versioning setup. Efforts in this direction are postponed to future major releases when the above process is more battle-tested.