Releasing frontend modules
After meeting a reasonable threshold of commits, or after a set period of time, you will likely want to publish your software to the NPM registry so that consumers can get your latest stable versions.
We are working with a bi-weekly release cadence of O3, meaning we publish new versions of our frontend modules every two weeks. This cadence is subject to change as we get more experience with the process.
Publishing an O3 release involves two steps:
- Bumping your local package versions and pushing those changes to GitHub. This step will trigger the CI's
- Cutting a release using the Github releases UI. This step triggers the
If you want to publish a release version of your module, you need to think about a few things first, including:
type- the semantic versioning release type (opens in a new tab) your changes conform to. Our release versions use the semver spec, meaning we have three release types:
patch- when you make backwards-compatible bug fixes.
minor- when you add functionality in a backwards-compatible manner.
major- when you make incompatible API changes.
For example, if the most recently released version number for a frontend module is
patchversion would increment the version number to
minorversion would increment the version number to
majorversion would increment the version number to
With that knowledge, you can proceed to draft a changelog. To do so:
- Go to the
releasespage of your monorepo, and click
Draft a new release.
- Click the
Choose a tagbutton in the releases page UI. Choose any tag, say
patchrelease if the most recent version is
v1.0.0. We will likely change this shortly after reviewing the changelog. Set that value as the release title as well. Next, click the
Generate release notesbutton.
We have established a convention within O3 where PR titles contain a conventional commit
type value that describes the kind of change the PR makes. These include:
(feat)for new features
(fix)for bug fixes
(chore)for housekeeping tasks, like managing dependencies, configuring things or updating CI workflows
(BREAKING)for backwards-incompatible API changes.
Reviewing the generated changelog with these commit types in mind should give you a good idea of the kind of semantic version bump your release should create. At this point, you can switch to your IDE to initiate the release process. Typically, we use lerna to version frontend modules. Run the following command at the root of your monorepo to trigger a version bump:
yarn lerna version [release type] --no-git-tag-version --no-push --yes --sort
For example, if you want to do a
major release, you would run:
yarn lerna version major --no-git-tag-version --no-push --yes --sort
- Bumps the
majorversion number for all the packages in your monorepo. For example, if the current version is
1.0.0, it would get bumped to
- Tells lerna not to create a git tag for the release.
- Tells lerna not to push the release to GitHub.
- Tells lerna to skip any confirmation prompts by passing the
--yesflag. We want to automate the release process as much as possible
- Tells lerna to force a version bump for all packages in your monorepo, even if they have not changed since the last release.
- Tells lerna This sorts the packages before running the commands so that they run on the packages in topological order (i.e., packages that depend on other packages get run later).
Once this process completes, you should see a diff in your editor that includes a version bump for all the packages in your monorepo and a change to your
lerna.json file. Run
yarn install to update your
yarn.lock file. Commit these changes with the title
(chore) Release vx.x.x where x.x.x is a placeholder for the version number. See an example of this commit (opens in a new tab) that bumps
Patient Chart to
Once your release commit is merged, the CI workflow's
pre-release job gets triggered and initiates a version bump for the corresponding version tagged
latest on NPM. This version is what consumers get when they install your frontend module.
You can then switch to your browser and head back to the releases page of the repo you are working with. Review the release notes generated by GitHub and then update the version number and tags appropriately. Once you are satisfied that everything looks ok, click the
Publish release button. This step should trigger the CI workflow and, notably, the
Under the hood, that job runs the following script:
"ci:publish-next": "lerna publish from-package --no-git-reset --dist-tag next --yes",
This command publishes a new package tagged
next. This is the version that consumers will get when they install your frontend module with the
next tag. This is useful for testing new features before they get released to the
Broadly speaking, when a PR gets merged, a
pre-release job in our primary GitHub actions CI workflow gets triggered. This job publishes a version of the frontend module to its corresponding npm registry tagged
latest. This is the version that consumers will get when they install your frontend module.
To see what version the
latest tag corresponds to for a frontend module, go to its NPM registry page and click on the
version tag. Look out for the most recent version tagged