docs: new release process

docs/publishing.md

@@ -1,37 +1,46 @@
 # Publishing a new version of `@mdn/browser-compat-data`
 
-[Project owners](./GOVERNANCE.md#owners) publish new releases of [`@mdn/browser-compat-data`](https://www.npmjs.com/package/@mdn/browser-compat-data) on npm, usually every Tuesday and Friday.
-MDN staff then deploy the package to the MDN site, usually every Thursday (MDN never deploys to production on Fridays).
+[Project owners](./GOVERNANCE.md#owners) publish new releases of the [`@mdn/browser-compat-data`](https://www.npmjs.com/package/@mdn/browser-compat-data) NPM package, usually every Tuesday and Friday.
 
-## Before you begin
+The release process is mostly automated using two GitHub workflows:
 
-Any project owner (or release designee) can complete the following steps to publish a new version.
-
-The steps in this process assume:
-
-- `NPM_TOKEN` is set in the repository secrets. If the token is invalidated or unset, a member of the `@mdn` organization on npm must [create a new token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) and [add it to the repository's secrets](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository).
-- You have cloned the mdn/browser-compat-data repository and you have the latest `main` branch checked out.
-- You have permissions to merge pull requests and publish releases.
-- You have [the `gh` CLI](https://cli.github.com/) installed.
-- You have [`jq`](https://stedolan.github.io/jq/) installed.
+1. The [`release-pr` workflow](https://github.com/mdn/browser-compat-data/blob/main/.github/workflows/release-pr.yml) manages a pull request draft that bumps the `package.json` version and updates the release notes.
+2. The [`release` workflow](https://github.com/mdn/browser-compat-data/blob/main/.github/workflows/release.yml) creates the GitHub release and tag, and publishes the release on NPM.
 
 ## Performing a release
 
-Releasing a new version of BCD is a two-step process: first, the release script is run to bump version number, generate the changelog, and create a pull request; then, once the pull request is merged, a release on GitHub is performed.
+A release is usually performed by merging the pull request managed by the `release-pr` workflow:
 
-First, run `npm run release`. This will automatically perform all of the steps needed to release a new version of BCD. If user input is needed, the script will announce as such. Once the script is complete, a pull request to release a new version of BCD will be created from your GitHub account, which can be reviewed and merged.
+1. The merge commit will trigger the `create-release` job of the `release` workflow.
+2. The `create-release` job publishes a [GitHub release](https://github.com/mdn/browser-compat-data/releases) and [tag](https://github.com/mdn/browser-compat-data/tags) based on the updated `package.json` and release notes.
+3. The published GitHub release will trigger 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](https://github.com/mdn/bcd-utils) repository, which triggers the deployment of the new BCD release on MDN.
 
-Once you have gotten the applicable review on your PR, it's time to finish the release process:
+### Before merging the release PR
 
-1. Merge the pull request created by the script.
+> [!WARNING]
+>
+> To ensure the release PR is up-to-date, care should be taken that no other PR is merged at the same time, and that all checks have passed on the latest `main` commit.
 
-2. Start a [release on GitHub](https://github.com/mdn/browser-compat-data/releases).
+> [!TIP]
+>
+> For major and minor releases, the `RELEASE_NOTES.md` can be edited manually on the `release` branch. However, as the next `release-pr` workflow run will overwrite the changes, it is advisable to keep a copy, or to disable the workflow temporarily.
 
-   - In the _Tag version_ and _Release title_ fields, enter `vX.Y.Z` where `X.Y.Z` in the version number in `package.json`.
-   - In the _Describe this release_ field, paste the release note text from `RELEASE_NOTES.md`, after (but not including) the release date.
+## Behind the scenes
 
-3. Click **Publish release** to create the tag and trigger the workflow that publishes to npm. Wait for the release [GitHub Actions workflow](https://github.com/mdn/browser-compat-data/actions) to finish successfully.
+The `release-pr` workflow runs `npm run release` with a personal access token (PAT) that is owned by [@mdn-bot](https://github.com/mdn-bot), and has read and write access to code and pull requests on the repository.
 
-4. Check [`@mdn/browser-compat-data` on npm](https://www.npmjs.com/package/@mdn/browser-compat-data) to see if the release shows up correctly. Note that this may take a while.
+The release script performs the following steps:
 
-The package is now published and you have finished releasing BCD! 🎉
+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 PRs 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, and creates or updates the release PR accordingly.