From fdb82434a95db01473a065bfa49d57f6fa1e0ea5 Mon Sep 17 00:00:00 2001 From: Salah-Eddine Saakoun Date: Wed, 12 Mar 2025 23:59:06 +0100 Subject: [PATCH 1/6] docs: add interactive release mode documentation --- docs/contributing.md | 45 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 68e66d8a135..61e3963cff5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -189,7 +189,9 @@ Have changes that you need to release? There are a few things to understand: - Unlike clients, releases are not issued on a schedule; **anyone may create a release at any time**. Because of this, you may wish to review the Pull Requests tab on GitHub and ensure that no one else has a release candidate already in progress. If not, then you are free to start the process. - The release process is a work in progress. Further improvements to simplify the process are planned, but in the meantime, if you encounter any issues, please reach out to the Wallet Framework team. -Now for the process itself: +Now for the process itself, you have two options: + +### Option A: Manual Release Specification 1. **Start by creating the release branch.** @@ -211,6 +213,8 @@ Now for the process itself: Once you've made the requisite changes to the YAML file, save it and re-run `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors. + + 4. **Review and update changelogs for relevant packages.** Once the tool proceeds without issue, you will be on the new release branch. In addition, each package you intend to release has been updated in two ways: @@ -249,6 +253,45 @@ Now for the process itself: You're done! +### Option B: Interactive Mode + +You can use the interactive web UI to streamline the release process by running: +`yarn create-release-branch -i` + +This will: + +1. Start a local web server (default port 3000) + +2. Open a browser interface showing all packages with changes since their last release + +3. Allow you to visually select which packages to include in the release + +4. Provide instant validation of your selections, including: + + - Identifying packages that need updates when their dependencies are being released + - Flagging packages that need to be included when their peer dependencies are being updated + - Validating version bumps against semantic versioning rules + - Ensuring all necessary dependent packages are included in the release + +5. Once your selections are complete, it will directly create the release branch with all necessary version bumps and changelog updates + +For example: + +- If you're releasing Package A that depends on Package B, the UI will prompt you to include Package B +- If you're releasing Package B with breaking changes, the UI will identify any packages that have peer dependencies on Package B that need to be updated + +You can specify a different port if needed: +`yarn create-release-branch -i -p 3001` + +The interactive UI simplifies the release process by: + +- Providing immediate feedback on your package selections +- Visualizing package dependencies and relationships +- Ensuring complete and valid release configurations +- Eliminating the need to manually edit release specifications + +After completing your selections in the UI, proceed to [reviewing and updating changelogs](#review-changelogs). + ## Performing operations across the monorepo This repository relies on Yarn's [workspaces feature](https://yarnpkg.com/features/workspaces) to provide a way to work with packages individually and collectively. Refer to the documentation for the following Yarn commands for usage instructions: From 1a5b5659a047a6931c17b0b65c02b1a16743fa76 Mon Sep 17 00:00:00 2001 From: Salah-Eddine Saakoun Date: Thu, 13 Mar 2025 15:23:03 +0100 Subject: [PATCH 2/6] docs: remove release summary --- docs/contributing.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 61e3963cff5..fd9cec22079 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -283,13 +283,6 @@ For example: You can specify a different port if needed: `yarn create-release-branch -i -p 3001` -The interactive UI simplifies the release process by: - -- Providing immediate feedback on your package selections -- Visualizing package dependencies and relationships -- Ensuring complete and valid release configurations -- Eliminating the need to manually edit release specifications - After completing your selections in the UI, proceed to [reviewing and updating changelogs](#review-changelogs). ## Performing operations across the monorepo From d3e57744358f9352a288a2b06f9b8c476c3e3972 Mon Sep 17 00:00:00 2001 From: Salah-Eddine Saakoun Date: Tue, 18 Mar 2025 15:53:11 +0100 Subject: [PATCH 3/6] Update documentation as per reviews --- docs/contributing.md | 121 +++++++++++++++++++++++++------------------ 1 file changed, 71 insertions(+), 50 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index fd9cec22079..ff44cdd99a8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -189,101 +189,122 @@ Have changes that you need to release? There are a few things to understand: - Unlike clients, releases are not issued on a schedule; **anyone may create a release at any time**. Because of this, you may wish to review the Pull Requests tab on GitHub and ensure that no one else has a release candidate already in progress. If not, then you are free to start the process. - The release process is a work in progress. Further improvements to simplify the process are planned, but in the meantime, if you encounter any issues, please reach out to the Wallet Framework team. -Now for the process itself, you have two options: +Now for the process itself, you have two options: using our interactive UI (recommended for most users) or manual specification. -### Option A: Manual Release Specification +### Option A: Interactive Mode (Recommended) -1. **Start by creating the release branch.** +This option provides a visual interface to streamline the release process: - On the `main` branch, run `yarn create-release-branch`. This command creates a branch named `release/` which will represent the new release. +1. **Start the interactive release tool.** -2. **Specify packages to release along with their versions.** + On the `main` branch, run: - Unless you've made a lot of breaking changes, you probably don't want to publish a new version of every single package in this repo. Fortunately, you can choose a subset of packages to include in the next release. 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 for more information. + ``` + yarn create-release-branch -i + ``` - In addition to selecting a list of packages, you'll also want to tell the tool which new versions they ought to receive. Since you'll want to follow SemVer, how you bump a package depends on the nature of the changes. You can understand these changes better by opening the changelog for each package in your editor. + This will start a local web server (default port 3000) and open a browser interface. - Once you save and close the release spec, the tool will proceed. +2. **Select packages to release.** -3. **Include more packages as necessary.** + The UI will show all packages with changes since their last release. For each package: - Some packages in the monorepo have dependencies on other packages elsewhere in the monorepo. To ensure that clients are able to upgrade without receiving compile time or runtime errors, you may need to include some of these dependencies in your release. If the tool thinks that there are some packages you've left out, it will pause and let you know what they are. + - Choose whether to include it in the release + - Select an appropriate version bump (patch, minor, or major) following SemVer rules + - The UI will automatically validate your selections and identify dependencies that need to be included - To address the errors, you'll need to copy the path to the YAML file, reopen it in your editor, and include the packages it mentions. You also have the option to skip any packages you think aren't an issue, but make sure you've checked. (If you have any questions about this step, let the Wallet Framework team know.) +3. **Review dependency requirements.** - Once you've made the requisite changes to the YAML file, save it and re-run `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors. + The tool will automatically: - + - Identify packages that need updates when their dependencies are being released + - Flag packages that need to be included when their peer dependencies are being updated + - Validate version bumps against semantic versioning rules + - Ensure all necessary dependent packages are included in the release -4. **Review and update changelogs for relevant packages.** +4. **Confirm your selections.** - Once the tool proceeds without issue, you will be on the new release branch. In addition, each package you intend to release has been updated in two ways: + Once you're satisfied with your package selections and version bumps, confirm them in the UI. This will: - - The version in `package.json` has been bumped. - - A new section has been added at the top of `CHANGELOG` for the new version. + - Create a new branch named `release/` + - Update the version in each package's `package.json` + - Add a new section to each package's `CHANGELOG.md` for the new version - At this point, you need to review the changelog entries and ensure that they are helpful for consumers: +5. **Review and update changelogs.** - - Categorize entries appropriately following the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/) guidelines. Ensure that no changes are listed under "Uncategorized". - - 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. + Each selected package will have a new changelog section. Review these entries to ensure they are helpful for consumers: - Make sure to run `yarn changelog:validate` once you're done to ensure all changelogs are correctly formatted. + - 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) + - Reword entries to explain changes in terms that users of the package will understand + - Consolidate related changes into single entries where appropriate -5. **Push and submit a pull request for the release branch so that it can be reviewed and tested.** + Run `yarn changelog:validate` when you're done to ensure all changelogs are correctly formatted. +6. **Push and submit a pull request.** + + Create a PR for the release branch so that it can be reviewed and tested. Release PRs can be approved by codeowners of affected packages, so as long as the above guidelines have been followed, there is no need to reach out to the Wallet Framework team for approval. -6. **Incorporate new changes made to `main` into changelogs.** +7. **Incorporate any new changes from `main`.** - If at any point you see the "Update branch" button on your release PR, stop and look over the most recent commits made to `main`. If there are new changes to package you are trying to release, make sure that the changes are reflected in the changelog for that package. + If you see the "Update branch" button on your release PR, stop and look over the most recent commits made to `main`. If there are new changes to packages you are releasing, make sure they are reflected in the appropriate changelogs. -7. **"Squash & Merge" the release and wait for approval.** +8. **Merge the release PR and wait for approval.** - You're almost there! + "Squash & Merge" the release PR when it's approved. Merging triggers the [`publish-release` GitHub action](https://github.com/MetaMask/action-publish-release) workflow to tag the final release commit and publish the release on GitHub. Before packages are published to NPM, this action will automatically notify the [`npm-publishers`](https://github.com/orgs/MetaMask/teams/npm-publishers) team in Slack to review and approve the release. -8. **Verify that the new versions have been published.** +9. **Verify publication.** Once the `npm-publishers` team has approved the release, you can click on the link in the Slack message to monitor the remainder of the process. - Once the action has completed, [check NPM](https://npms.io/search?q=scope%3Ametamask) to verify that all relevant packages has been published. + After the action has completed, [check NPM](https://npms.io/search?q=scope%3Ametamask) to verify that all relevant packages have been published. - You're done! +> **Tip:** You can specify a different port if needed: `yarn create-release-branch -i -p 3001` -### Option B: Interactive Mode +### Option B: Manual Release Specification -You can use the interactive web UI to streamline the release process by running: -`yarn create-release-branch -i` +If you prefer more direct control over the release process: -This will: +1. **Start by creating the release branch.** -1. Start a local web server (default port 3000) + On the `main` branch, run `yarn create-release-branch`. This command creates a branch named `release/` which will represent the new release. -2. Open a browser interface showing all packages with changes since their last release +2. **Specify packages to release along with their versions.** + + Unless you've made a lot of breaking changes, you probably don't want to publish a new version of every single package in this repo. Fortunately, you can choose a subset of packages to include in the next release. 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 for more information. + + In addition to selecting a list of packages, you'll also want to tell the tool which new versions they ought to receive. Since you'll want to follow SemVer, how you bump a package depends on the nature of the changes. You can understand these changes better by opening the changelog for each package in your editor. + + Once you save and close the release spec, the tool will proceed. + +3. **Include more packages as necessary.** + + Some packages in the monorepo have dependencies on other packages elsewhere in the monorepo. To ensure that clients are able to upgrade without receiving compile time or runtime errors, you may need to include some of these dependencies in your release. If the tool thinks that there are some packages you've left out, it will pause and let you know what they are. + + To address the errors, you'll need to copy the path to the YAML file, reopen it in your editor, and include the packages it mentions. You also have the option to skip any packages you think aren't an issue, but make sure you've checked. (If you have any questions about this step, let the Wallet Framework team know.) -3. Allow you to visually select which packages to include in the release + Once you've made the requisite changes to the YAML file, save it and re-run `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors. -4. Provide instant validation of your selections, including: +4. **Review and update changelogs for relevant packages.** - - Identifying packages that need updates when their dependencies are being released - - Flagging packages that need to be included when their peer dependencies are being updated - - Validating version bumps against semantic versioning rules - - Ensuring all necessary dependent packages are included in the release + Once the tool proceeds without issue, you will be on the new release branch. In addition, each package you intend to release has been updated in two ways: -5. Once your selections are complete, it will directly create the release branch with all necessary version bumps and changelog updates + - The version in `package.json` has been bumped. + - A new section has been added at the top of `CHANGELOG` for the new version. -For example: + At this point, you need to review the changelog entries and ensure that they are helpful for consumers: -- If you're releasing Package A that depends on Package B, the UI will prompt you to include Package B -- If you're releasing Package B with breaking changes, the UI will identify any packages that have peer dependencies on Package B that need to be updated + - Categorize entries appropriately following the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/) guidelines. Ensure that no changes are listed under "Uncategorized". + - 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. -You can specify a different port if needed: -`yarn create-release-branch -i -p 3001` + Make sure to run `yarn changelog:validate` once you're done to ensure all changelogs are correctly formatted. -After completing your selections in the UI, proceed to [reviewing and updating changelogs](#review-changelogs). +5. **Follow steps 6-9 from Option A above to complete the release.** ## Performing operations across the monorepo From 43cf3ac46f2ee3e0de046621b715dac21a094246 Mon Sep 17 00:00:00 2001 From: Salah-Eddine Saakoun Date: Tue, 18 Mar 2025 15:59:57 +0100 Subject: [PATCH 4/6] Add releasing validations examples --- docs/contributing.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index ff44cdd99a8..6c8b149f37e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -213,14 +213,20 @@ This option provides a visual interface to streamline the release process: - Select an appropriate version bump (patch, minor, or major) following SemVer rules - The UI will automatically validate your selections and identify dependencies that need to be included -3. **Review dependency requirements.** +3. **Review and resolve dependency requirements.** - The tool will automatically: + The UI automatically analyzes your selections and identifies potential dependency issues that need to be addressed before proceeding. You'll need to review and resolve these issues by either: - - Identify packages that need updates when their dependencies are being released - - Flag packages that need to be included when their peer dependencies are being updated - - Validate version bumps against semantic versioning rules - - Ensure all necessary dependent packages are included in the release + - Including the suggested additional packages + - Confirming that you want to skip certain packages (if you're certain they don't need to be updated) + + Common types of dependency issues you might encounter: + + - **Missing dependencies**: If you're releasing Package A that depends on Package B, the UI will prompt you to include Package B + - **Breaking change impacts**: If you're releasing Package B with breaking changes, the UI will identify packages that have peer dependencies on Package B that need to be updated + - **Version incompatibilities**: The UI will flag if your selected version bumps don't follow semantic versioning rules relative to dependent packages + + Unlike the manual workflow where you need to repeatedly edit a YAML file, in the interactive mode you can quickly resolve these issues by checking boxes and selecting version bumps directly in the UI. 4. **Confirm your selections.** @@ -280,13 +286,20 @@ If you prefer more direct control over the release process: Once you save and close the release spec, the tool will proceed. -3. **Include more packages as necessary.** +3. **Review and resolve dependency requirements.** + + The UI automatically analyzes your selections and identifies potential dependency issues that need to be addressed before proceeding. You'll need to review and resolve these issues by either: + + - Including the suggested additional packages + - Confirming that you want to skip certain packages (if you're certain they don't need to be updated) - Some packages in the monorepo have dependencies on other packages elsewhere in the monorepo. To ensure that clients are able to upgrade without receiving compile time or runtime errors, you may need to include some of these dependencies in your release. If the tool thinks that there are some packages you've left out, it will pause and let you know what they are. + Common types of dependency issues you might encounter: - To address the errors, you'll need to copy the path to the YAML file, reopen it in your editor, and include the packages it mentions. You also have the option to skip any packages you think aren't an issue, but make sure you've checked. (If you have any questions about this step, let the Wallet Framework team know.) + - **Missing dependencies**: If you're releasing Package A that depends on Package B, the UI will prompt you to include Package B + - **Breaking change impacts**: If you're releasing Package B with breaking changes, the UI will identify packages that have peer dependencies on Package B that need to be updated + - **Version incompatibilities**: The UI will flag if your selected version bumps don't follow semantic versioning rules relative to dependent packages - Once you've made the requisite changes to the YAML file, save it and re-run `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors. + Unlike the manual workflow where you need to repeatedly edit a YAML file, in the interactive mode you can quickly resolve these issues by checking boxes and selecting version bumps directly in the UI. 4. **Review and update changelogs for relevant packages.** From 20a07167f1d06f1fe7bbfe56efdcd240152c5ac7 Mon Sep 17 00:00:00 2001 From: Salah-Eddine Saakoun Date: Tue, 18 Mar 2025 21:06:52 +0100 Subject: [PATCH 5/6] Update documentation as per second round of reviews --- docs/contributing.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 6c8b149f37e..8a8d9ac2ec7 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -240,10 +240,10 @@ This option provides a visual interface to streamline the release process: Each selected package will have a new changelog section. Review these entries to ensure they are helpful for consumers: - - 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) - - Reword entries to explain changes in terms that users of the package will understand - - Consolidate related changes into single entries where appropriate + - Categorize entries appropriately following the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/) guidelines. Ensure that no changes are listed under "Uncategorized". + - 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. Run `yarn changelog:validate` when you're done to ensure all changelogs are correctly formatted. @@ -288,7 +288,7 @@ If you prefer more direct control over the release process: 3. **Review and resolve dependency requirements.** - The UI automatically analyzes your selections and identifies potential dependency issues that need to be addressed before proceeding. You'll need to review and resolve these issues by either: + The tool automatically analyzes your selections and identifies potential dependency issues that need to be addressed before proceeding. You'll need to review and resolve these issues by either: - Including the suggested additional packages - Confirming that you want to skip certain packages (if you're certain they don't need to be updated) @@ -299,7 +299,7 @@ If you prefer more direct control over the release process: - **Breaking change impacts**: If you're releasing Package B with breaking changes, the UI will identify packages that have peer dependencies on Package B that need to be updated - **Version incompatibilities**: The UI will flag if your selected version bumps don't follow semantic versioning rules relative to dependent packages - Unlike the manual workflow where you need to repeatedly edit a YAML file, in the interactive mode you can quickly resolve these issues by checking boxes and selecting version bumps directly in the UI. + To address these issues, you will need to reopen the YAML file, modify it by either adding more packages to the release or omitting packages from the release you think are safe, and then re-running `yarn create-release-branch. You may need to repeat this step multiple times until you don't see any more errors. 4. **Review and update changelogs for relevant packages.** @@ -317,7 +317,26 @@ If you prefer more direct control over the release process: Make sure to run `yarn changelog:validate` once you're done to ensure all changelogs are correctly formatted. -5. **Follow steps 6-9 from Option A above to complete the release.** +5. **Push and submit a pull request.** + + Create a PR for the release branch so that it can be reviewed and tested. + Release PRs can be approved by codeowners of affected packages, so as long as the above guidelines have been followed, there is no need to reach out to the Wallet Framework team for approval. + +6. **Incorporate any new changes from `main`.** + + If you see the "Update branch" button on your release PR, stop and look over the most recent commits made to `main`. If there are new changes to packages you are releasing, make sure they are reflected in the appropriate changelogs. + +7. **Merge the release PR and wait for approval.** + + "Squash & Merge" the release PR when it's approved. + + Merging triggers the [`publish-release` GitHub action](https://github.com/MetaMask/action-publish-release) workflow to tag the final release commit and publish the release on GitHub. Before packages are published to NPM, this action will automatically notify the [`npm-publishers`](https://github.com/orgs/MetaMask/teams/npm-publishers) team in Slack to review and approve the release. + +8. **Verify publication.** + + Once the `npm-publishers` team has approved the release, you can click on the link in the Slack message to monitor the remainder of the process. + + After the action has completed, [check NPM](https://npms.io/search?q=scope%3Ametamask) to verify that all relevant packages have been published. ## Performing operations across the monorepo From 77f27fcfb1335164dfc97c2aa54087dae319f176 Mon Sep 17 00:00:00 2001 From: cryptodev-2s <109512101+cryptodev-2s@users.noreply.github.com> Date: Tue, 18 Mar 2025 21:55:38 +0100 Subject: [PATCH 6/6] Update contributing.md Co-authored-by: Elliot Winkler --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 8a8d9ac2ec7..c9dde4e0188 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -299,7 +299,7 @@ If you prefer more direct control over the release process: - **Breaking change impacts**: If you're releasing Package B with breaking changes, the UI will identify packages that have peer dependencies on Package B that need to be updated - **Version incompatibilities**: The UI will flag if your selected version bumps don't follow semantic versioning rules relative to dependent packages - To address these issues, you will need to reopen the YAML file, modify it by either adding more packages to the release or omitting packages from the release you think are safe, and then re-running `yarn create-release-branch. You may need to repeat this step multiple times until you don't see any more errors. + To address these issues, you will need to reopen the YAML file, modify it by either adding more packages to the release or omitting packages from the release you think are safe, and then re-running `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors. 4. **Review and update changelogs for relevant packages.**