Publishing a new version of @mdn/browser-compat-data

New releases of the @mdn/browser-compat-data NPM package are published twice per week on Tuesday and Friday, except during year-end holidays.

The release process is mostly automated using two GitHub workflows:

  1. The release-pr workflow manages a pull request that bumps the package.json version and updates the release notes.
  2. The release workflow creates the GitHub release and tag, publishes the release on NPM, and triggers MDN deployment.

The release itself is triggered manually, to help ensure that as many ready pull requests make it into the release.

Performing a release

Any project owner (or release designee) can complete the following steps to publish a new version.

To publish a release:

  1. If this is a major or minor release: Align with project owners on the release notes entries, i.e. “Breaking changes” for major releases, and “Notable changes” for major/minor releases.
  2. Mark the release pull request (titled Release vX.Y.Z) as ready for review.
  3. Ensure that the pull request is up-to-date, i.e. that all checks have passed on the latest main commit, and that no other pull request is merged right before.
  4. If this is a major or minor release: Add the release notes entries manually to the RELEASE_NOTES.md on the release branch (below the release date).
  5. Merge the pull request.

Behind the scenes

The release pull request is managed by the release-pr workflow, which runs npm run release with a personal access token (PAT) that is owned by @mdn-bot, and has read and write access to code and pull requests on the repository.

The release script performs the following steps:

  1. Fetches the latest main branch.
  2. Determines the previous release version.
  3. Determines whether a major or minor version bump is needed, based on pull requests with the semver-major-bump or semver-minor-bump label merged since the previous release.
  4. Updates the package.json by running npm version.
  5. Updates the RELEASE_NOTES.md by determining release notes based on the following input:
    • Release and repository statistics.
    • List of added and removed features, determined by iterating over all merged pull requests since the previous release, and enumerating all features before and after the merge commit.
  6. Commits and pushes the changes to the release branch.
  7. Creates or updates the release pull request accordingly.

Merging the release pull request yields the following result:

  1. The merge commit triggers the create-release job of the release workflow workflow.
  2. The create-release job publishes a GitHub release and tag based on the updated package.json and release notes.
  3. The published GitHub release triggers the publish-release job of the release workflow.
  4. The publish-release job performs the following steps:
    • Builds the release.
    • Publishes the release to NPM.
    • Adds the data.json as an asset to the GitHub release.
    • Dispatches a bcd_release event on the mdn/bcd-utils repository, which triggers the deployment of the new BCD release on MDN.