Releasing frontend modules

After meeting a reasonable threshold of commits, or after a set 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:

1. Bumping your local package versions and pushing those changes to GitHub. This step will trigger the CI's pre-release job.
2. Cutting a release using the Github releases UI. This step triggers the release CI job.

If you want to publish a release version of your module, you need to think about a few things first, including:

• The release 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 v1.0.0:

  • A patch version would increment the version number to 1.0.1.
  • A minor version would increment the version number to 1.1.0.
  • A major version would increment the version number to 2.0.0.

With that knowledge, you can draft a changelog. To do so:

• Go to the releases page of your monorepo, and click Draft a new release.
• Click the Choose a tag button in the releases page UI. Choose any tag, say v1.0.1 for a patch release 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 notes button.

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
• (refactor) for refactors
• (test) for tests
• (docs) for documentation
• (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 semantic version bump your release should create. At this point, you can switch to your IDE to initiate the release process. Typically, we use yarn to version frontend modules. Run the following command at the root of your monorepo to trigger a version bump:

yarn workspaces foreach --worktree --topological --exclude [monorepo-name] version [release-type]

For example, if you want to do a major release in esm-patient-management, you would run:

yarn workspaces foreach --worktree --exclude @openmrs/esm-patient-management version major

This command:

• Runs the version command against all the packages in the workspace and bumps them to a major version. For example, if the current version is 1.0.0, it would get bumped to 2.0.0.first-letter.
• Tells yarn to sort 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).
• Tells yarn to exclude versioning for the selected monorepo so that the package.json in the root directory is unaffected. The root package.json does not require a version for publishing purposes because it is never published.

Once this process completes, you should see a diff in your editor that includes a version bump for all the packages in your monorepo. Run yarn or 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 v5.0.0.

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 release job.

Under the hood, that job runs the following script:

"ci:prepublish": "yarn workspaces foreach --all --topological npm publish --access public --tag next",

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 latest tag.

Broadly speaking, when a PR is 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 latest.