Update releasing process (#3592)

## Explanation This PR updates the release process to take in considerations recent changes on create-release-branch. - Compel users to release packages with breaking changes alongside their dependents [MetaMask/create-release-branch#101] - Compel users to release new versions of dependencies alongside their dependents [MetaMask/create-release-branch#102] - Reorder workflow to update changelogs first [MetaMask/create-release-branch#109] ## References - Closes #1741 ## Changelog N/A ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've highlighted breaking changes using the "BREAKING" category above as appropriate
MetaMask · Dec 7, 2023 · d7bc126 · d7bc126
1 parent 45fd71b
commit d7bc126
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 27 deletions.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -163,28 +163,32 @@ To use a preview build for a package within a project, you need to override the
 
 The [`create-release-branch`](https://github.com/MetaMask/create-release-branch) tool and [`action-publish-release`](https://github.com/MetaMask/action-publish-release) GitHub action are used to automate the release process.
 
-1. **Create a release branch.**
+1. **Initiate the release branch and specify packages to be released.**
 
-   Run `yarn create-release-branch`. This tool generates a file and opens it in your editor, where you can specify which packages you want to include in the next release and which versions they should receive. Instructions are provided for you at the top; read them and update the file accordingly.
+   1. **Create the release branch.**
 
-   When you're ready to continue, save and close the file.
+      Start by running `yarn create-release-branch`. This command creates a branch named `release/<new release version>` which will represent the new release.
 
-2. **Update changelogs for relevant packages.**
+   2. **Specify packages to release along with their versions.**
 
-   At this point you will be on a new release branch, and a new section will have been added to the changelog of each package you specified in the previous step.
+      At this point, you need to tell the tool which packages you want to include in the next release and which versions to assign to those packages. You do this by modifying a YAML file called a "release spec", which the tool has generated and opened it in your editor. Follow the instructions at the top of the file to proceed.
 
-   For each changelog, review the new section and make the appropriate changes:
+      To assist you, the tool has also updated all of the packages that have been changed since their previous releases so that their changelogs now reflect those new changes. This should help you to understand what will be released and how to bump the versions.
 
-   - Move each entry into the appropriate category (review the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/#types) spec for the full list of categories and the correct ordering of all categories).
-   - Remove any changelog entries that don't affect consumers of the package (e.g. lockfile changes or development environment changes). Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.).
-   - Reword changelog entries to explain changes in terms that users of the package will understand (e.g., avoid referencing internal variables/concepts).
-   - Consolidate related changes into one change entry if it makes it easier to comprehend.
+      Once you save and close the release spec, the tool will proceed.
 
-   Run `yarn changelog:validate` to check that all changelogs are correctly formatted.
+2. **Review and update changelogs for relevant packages.**
 
-   Commit and push the branch.
+   1. At this point, the versions of all packages you intend to release have been bumped and their changelogs list new changes. Now you need to go through each changelog and make sure that they follow existing standards:
 
-3. **Submit a pull request for the release branch so that it can be reviewed and tested.**
+      - Categorize entries appropriately following the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/) guidelines.
+      - Remove changelog entries that don't affect consumers of the package (e.g. lockfile changes or development environment changes). Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.).
+      - Reword changelog entries to explain changes in terms that users of the package will understand (e.g., avoid referencing internal variables/concepts).
+      - Consolidate related changes into single entries where appropriate.
+
+   2. Run `yarn changelog:validate` to ensure all changelogs are correctly formatted.
+
+3. **Push and submit a pull request for the release branch so that it can be reviewed and tested.**
 
    Make sure the title of the pull request follows the pattern "Release \<new version\>".
 
@@ -201,3 +205,26 @@ The [`create-release-branch`](https://github.com/MetaMask/create-release-branch)
    The `publish-release` GitHub Action workflow runs the `publish-npm` job, which publishes relevant packages to NPM. It requires approval from the [`npm-publishers`](https://github.com/orgs/MetaMask/teams/npm-publishers) team to complete. If you're not on the team, ask a member to approve it for you; otherwise, approve the job.
 
    Once the `publish-npm` job has finished, [check NPM](https://npms.io/search?q=scope%3Ametamask) to verify that all relevant packages has been published.
+
+### Handling common errors
+
+If an error occurs, re-edit the release spec and rerun `yarn create-release-branch`. Common errors include:
+
+- **Invalid Version Specifier:**
+
+  - Error: `* Line 14: "invalid_version" is not a valid version specifier...`
+  - Resolution: Use "major", "minor", "patch", or a specific version number like "1.2.3".
+
+- **Version Less than or Equal to Current:**
+
+  - Error: `* Line 14: "1.2.3" is not a valid version specifier...`
+  - Resolution: Specify a version greater than the current version of the package.
+
+- **Releasing Packages with Breaking Changes:**
+
+  - Error: `* The following dependents of package '@metamask/a'...`
+  - Resolution: Include dependent packages in the release or use "intentionally-skip" if certain they are unaffected.
+
+- **Dependencies/Peer Dependencies Missing:**
+  - Error: `* The following packages, which are dependencies...`
+  - Resolution: Include necessary dependencies or peer dependencies in the release or use "intentionally-skip" if certain they are unaffected.
diff --git a/package.json b/package.json
@@ -39,7 +39,7 @@
   },
   "devDependencies": {
     "@lavamoat/allow-scripts": "^2.3.1",
-    "@metamask/create-release-branch": "^1.1.0",
+    "@metamask/create-release-branch": "^2.0.1",
     "@metamask/eslint-config": "^12.2.0",
     "@metamask/eslint-config-jest": "^12.1.0",
     "@metamask/eslint-config-nodejs": "^12.1.0",

diff --git a/yarn.lock b/yarn.lock
@@ -1532,6 +1532,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@metamask/auto-changelog@npm:~3.3.0":
+  version: 3.3.0
+  resolution: "@metamask/auto-changelog@npm:3.3.0"
+  dependencies:
+    diff: ^5.0.0
+    execa: ^5.1.1
+    prettier: ^2.8.8
+    semver: ^7.3.5
+    yargs: ^17.0.1
+  bin:
+    auto-changelog: dist/cli.js
+  checksum: 1b308f0f6beafb479da19398bc51315888c8fa7e1688ee835a96d5e2ca8dccf2edac80ac835335122b2c3ff6c76f03d202a35316122bbfa7c071954d5227f732
+  languageName: node
+  linkType: hard
+
 "@metamask/base-controller@^4.0.0, @metamask/base-controller@workspace:packages/base-controller":
   version: 0.0.0-use.local
   resolution: "@metamask/base-controller@workspace:packages/base-controller"
@@ -1657,7 +1672,7 @@ __metadata:
   resolution: "@metamask/core-monorepo@workspace:."
   dependencies:
     "@lavamoat/allow-scripts": ^2.3.1
-    "@metamask/create-release-branch": ^1.1.0
+    "@metamask/create-release-branch": ^2.0.1
     "@metamask/eslint-config": ^12.2.0
     "@metamask/eslint-config-jest": ^12.1.0
     "@metamask/eslint-config-nodejs": ^12.1.0
@@ -1693,22 +1708,23 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@metamask/create-release-branch@npm:^1.1.0":
-  version: 1.1.0
-  resolution: "@metamask/create-release-branch@npm:1.1.0"
+"@metamask/create-release-branch@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "@metamask/create-release-branch@npm:2.0.1"
   dependencies:
     "@metamask/action-utils": ^1.0.0
-    "@metamask/utils": ^5.0.2
+    "@metamask/auto-changelog": ~3.3.0
+    "@metamask/utils": ^8.2.1
     debug: ^4.3.4
     execa: ^5.1.1
     pony-cause: ^2.1.9
-    semver: ^7.5.0
+    semver: ^7.5.4
     which: ^3.0.0
     yaml: ^2.2.2
     yargs: ^17.7.1
   bin:
     create-release-branch: bin/create-release-branch.js
-  checksum: 04ab235f27768c8977fe998da6b4f09eccd384debb80dcafda6c4a5ea59638c414b2e6a2ebd770471946f050ae6eaf1c2d798d06ff0b38c0585d6dc17a62cab4
+  checksum: a81ae6a9f8e87e3118c0df33dfd5f692a6d49863ca4d03956917c8239fb69a743181396423fc41f6271373438c61b3d126e20e299739ce46191fe38022c75751
   languageName: node
   linkType: hard
 
@@ -2722,7 +2738,7 @@ __metadata:
   languageName: unknown
   linkType: soft
 
-"@metamask/utils@npm:^5.0.0, @metamask/utils@npm:^5.0.2":
+"@metamask/utils@npm:^5.0.0":
   version: 5.0.2
   resolution: "@metamask/utils@npm:5.0.2"
   dependencies:
@@ -2749,9 +2765,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@metamask/utils@npm:^8.0.0, @metamask/utils@npm:^8.1.0, @metamask/utils@npm:^8.2.0":
-  version: 8.2.0
-  resolution: "@metamask/utils@npm:8.2.0"
+"@metamask/utils@npm:^8.0.0, @metamask/utils@npm:^8.1.0, @metamask/utils@npm:^8.2.0, @metamask/utils@npm:^8.2.1":
+  version: 8.2.1
+  resolution: "@metamask/utils@npm:8.2.1"
   dependencies:
     "@ethereumjs/tx": ^4.2.0
     "@noble/hashes": ^1.3.1
@@ -2761,7 +2777,7 @@ __metadata:
     pony-cause: ^2.1.10
     semver: ^7.5.4
     superstruct: ^1.0.3
-  checksum: 1c70c0f9c375bfa3836c15d48990dbea1c3cadfd3dd69b4867667116c09c3bdeef70a0c7027f1cdea88a9913cb846dc94812ece91be7ec32e65a62e00281b04c
+  checksum: 36a714a17e4949d2040bedb28d4373a22e7e86bb797aa2d59223f9799fd76e662443bcede113719c4e200f5e9d90a9d62feafad5028fff8b9a7a85fface097ca
   languageName: node
   linkType: hard
 
@@ -9524,7 +9540,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"semver@npm:7.x, semver@npm:^7.0.0, semver@npm:^7.3.2, semver@npm:^7.3.5, semver@npm:^7.3.7, semver@npm:^7.3.8, semver@npm:^7.5.0, semver@npm:^7.5.4":
+"semver@npm:7.x, semver@npm:^7.0.0, semver@npm:^7.3.2, semver@npm:^7.3.5, semver@npm:^7.3.7, semver@npm:^7.3.8, semver@npm:^7.5.4":
   version: 7.5.4
   resolution: "semver@npm:7.5.4"
   dependencies: