Skip to content

Releasing React Magma

Jump to bottom
Laura Silva edited this page Dec 16, 2024 · 18 revisions

react-magma uses @changesets/cli for versioning and publishing.

Github Workflows Publish Job

We have 2 Publish Workflows: publish-next.yml and publish-latest.yml

Next

Latest

  • Triggers when changes are pushed to the main branch
  • This releases a new version, depending on what changes are in the changeset (could be major, minor or patch version *️⃣).

Our publish-latest job runs the following commands:

npm run version:exit
npm run version:pkgs
git commit -am "chore: exit prerelease mode"
npm run release
git push --follow-tags

This assumes that the pre mode has already been entered (npm run version:prerelease)

npm run version:exit updates the pre.json file to exit mode.

npm run version:pkgs updates the changelog for all packages with the changeset updates, then deletes the changeset files. It also updates the package versions in the package.json files.

npm run release calls changeset publish releases to npm.

Steps to release from main branch

  1. Open a pull request to merge your change from dev -> main. ⭐
  • git checkout main
  • git pull
  • git checkout -b "build/releaseX.X.X"
  • git pull origin dev (or git merge dev)
  1. Resolve merge conflicts, if any. Run the unit tests to make sure they all pass.
  2. Ensure you have entered pre mode. If not, run the command npm run version:prerelease and push that change to the pre.json file to your branch.
  3. Clean up the CHANGELOG by removing all the entries of the patch versions. The CHANGELOG will be recreated on publish. You do NOT have to add react-magma-dom changes to the CHANGELOG.mdx as it happens automatically.
  4. Do some manual testing on the docs site and storybook to confirm all the changes behave as expected.
  5. After team approval and green build, merge the pull request.
  6. When this gets merged, the automation will automatically merge main back into dev (Sync main -> dev step) so the dev branch will be ready to go for future development. Occasionally, this step fails. Look below at 🔀 for details on how to fix it.
  7. After the release is complete, make an announcement in the #react-magma channel

Releasing from the patch branch

  1. First, ensure that patch-* -> dev-patch branches are in sync (whether automatically or manually after the release). Then, ensure that all commits in dev are also in dev-patch. If not, start by opening a PR in dev-patch that cherry-picks every commit from dev that should be part of this release. Note that any commits that update the package-lock may cause issues.
  2. Open a pull request to merge your change from dev-patch -> patch-3.x.x. ⭐
  • git checkout patch-3.x.x
  • git pull
  • git checkout -b "build/releaseX.X.X"
  • git pull origin dev-patch (or git merge dev-patch)
  1. Resolve merge conflicts. There will be some in the package.json files and changelog. Clean up the CHANGELOG by removing all the entries of the patch versions. Run the unit tests to make sure they all pass.
  2. Remove changelogs/changesets for any non-react-magma-dom change. We don't want to have 2 releases for the other packages. We DO want changes to the docs site and landing page!
  3. The version in the react-magma-dom package.json should be of the last released version. The pipeline process will up this version (depending on the changes, will release a major/minor/patch).
  4. Ensure you have entered pre mode. If not, run the command npm run version:prerelease and push that change to the pre.json file to your branch. The react-magma-dom version in this file should also have the last released version.

Gotchas

  • ⭐ Make sure you don't accidentally push a change to main before you intended to (for example, while fixing merge conflicts). ALL pushes to main will trigger the publish job and can lead to unwanted releases
  • To confirm what version is going to be released, you can locally run the Publish commands (without pushing it to the branch). The package.json files will get updated with npm run version:pkgs and you'll be able to see the version number you are publishing along with the updated dependencies.
  • 🔀 If the Sync main -> dev step fails, fix it manually by creating a new branch from dev, then git merge -X theirs main. Fix the merge conflicts by doing the following:
    • Remove all the .md changeset files from the .changeset directory
    • For the package.json files, resolve the conflicts with what is coming from main. Ultimately, we don't want the prerelease versions. Update something that looks like "version": "1.0.2-next.0" to be "version": "1.0.2".
    • For the Changelogs, make sure the logs look right and are up to date for the appropriate versions.
    • Example PR
  • *️⃣ If your changeset has different kinds of changes, the version for release will be flattened to the highest semver range:
Changesets are designed to be as easy to accumulate as possible. As such, when changesets are consumed with version, we flatten the version bumps into one single bump at the highest semver range specified.

For example: if you run version, and we have packageA at 1.1.1, which has two minor changesets, and one patch changeset, we will bump packageA to 1.2.1.
Clone this wiki locally