Document new process for releasing breaking changes (#7187)

## Explanation

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

In a future PR, we will convert all peer dependencies to dependencies.
When this happens, contributors need to follow a new process for
ensuring that breaking changes do not cause problems for other
developers or users. This PR adds the necessary documentation.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

Closes https://consensyssoftware.atlassian.net/browse/WPC-132.

## 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 communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces a breaking-changes process guide and updates contributor
docs, reviewing guide, and PR template checklist to reference and align
with it.
> 
> - **Documentation**:
> - **New guide**: Add `docs/breaking-changes.md` detailing what
constitutes a breaking change and the process to document, audit
dependents, and prepare upgrade PRs.
>   - **Contributor Guide** (`docs/contributing.md`):
>     - Add TOC entry and link to breaking-changes guide.
> - Highlight special handling for breaking changes in the release
process.
>   - **Reviewing Release PRs** (`docs/reviewing-release-prs.md`):
> - Replace inlined definition with concise definition and link to
`breaking-changes.md` for examples.
> - **PR Template** (`.github/pull_request_template.md`):
> - Update checklist items to separate changelog updates from
acknowledging/handling breaking changes with draft PRs.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
c0a30da. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mcmire

.github/pull_request_template.md

@@ -27,5 +27,5 @@ For example:
 
 - [ ] I've updated the test suite for new or updated code as appropriate
 - [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
-- [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs), highlighting breaking changes as necessary
-- [ ] I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes
+- [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs)
+- [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

docs/breaking-changes.md

@@ -0,0 +1,84 @@
+# Preparing & Releasing Breaking Changes
+
+When developing packages, it is always important to be intentional about the impact that changes have on projects which use those packages. However, special consideration must be given to breaking changes.
+
+This guide provides best practices for documenting, preparing, releasing, and adapting to breaking changes within `core` and in other projects.
+
+## What is a breaking change?
+
+A change to a package is "breaking" if upgrading a project to a version containing the change would require modifications to source code or configuration in order to avoid user- or developer-facing problems (an inability to use or build the project, a loss of functionality, etc.).
+
+There are many kinds of breaking changes. Here are some examples:
+
+- Removals
+  - Removing a method from a class
+  - Removing an export from a package (including a type export)
+- Functional changes that require code changes or change expectations
+  - Changing the number of required arguments for a function or method
+  - Throwing a new error in a function or method
+  - Changing a function or method so that it no longer fires an event
+- Breaking changes to types
+  - Adding external actions or events to a messenger type
+  - Narrowing the type of an argument in a function or method
+  - Changing the number of required properties in an object type
+  - Narrowing the type of a property in an object type
+  - Changing the number of type parameters for a type
+  - Making any other change listed [here](https://www.semver-ts.org/formal-spec/2-breaking-changes.html)
+- Bumping the minimum supported Node.js version of a package
+- Upgrading a dependency referenced in published code to a version that causes any of the above
+
+## Introducing breaking changes safely
+
+Before merging a PR that introduces breaking changes, it is important to ensure that they are accounted for among projects.
+
+### 1. Document breaking changes
+
+To inform other maintainers now and in the future, make sure that breaking changes are documented in the changelog:
+
+1. Be explicit in your changelog entries about which classes, functions, types, etc. are affected.
+2. Prefix entries with `**BREAKING:**`.
+3. If relevant, provide details on how consuming code can adapt to the changes safely.
+4. Move entries for breaking changes above all other kinds of changes within the same section.
+
+For example:
+
+```markdown
+### Changed
+
+- **BREAKING:** Add a required `source` argument to `getTransactions` ([#1111](https://github.com/MetaMask/core/pull/1111))
+- **BREAKING:** Rename `Prices` to `PricesResponse` ([#2222](https://github.com/MetaMask/core/pull/2222))
+- **BREAKING:** `destroy` is now async ([#3333](https://github.com/MetaMask/core/pull/3333))
+- Widen the type of `getNetworkClientId` to return `string` ([#4444](https://github.com/MetaMask/core/pull/4444))
+
+### Removed
+
+- **BREAKING:** Remove `fetchGasPrices` from `GasPricesController` ([#5555](https://github.com/MetaMask/core/pull/5555))
+  - Please use `GasPriceService` instead.
+```
+
+### 2. Audit dependents
+
+When you release your changes, which codebases will be affected?
+
+Using the changelog as a guide, locate all of the places across MetaMask that use the affected classes, functions, types, etc.:
+
+- To find dependents of your package within `core`, look in the package's `package.json`, or simply search across the repo.
+- To find dependents of your package across MetaMask, do a search on GitHub for import statements or, better, usages of the affected symbols.
+
+### 3. Prepare upgrade PRs for dependents
+
+Finally, how will dependent projects need to adapt to your breaking changes?
+
+For dependent packages located in `core`, you may get type errors immediately that you will have to fix in the same PR that introduces the breaking changes. Otherwise, create new PRs to migrate existing code.
+
+For other projects that live outside of `core`, you can use the following process to verify the effects:
+
+1. Create a [preview build](./contributing.md#testing-changes-to-packages-with-preview-builds) for your package.
+2. Open draft PRs in the dependent projects.
+3. In each draft PR, upgrade your package to the preview build.
+4. Test the project, particularly the functionality that makes use of your package.
+5. If you see compile-time or runtime errors, make changes to the project as necessary.
+6. If you discover new breaking changes in your package that you haven't yet listed in the changelog, go back and [document them](#1-document-breaking-changes).
+7. Once you've done this for all projects, check off the "I've followed the process for releasing breaking changes" item in the checklist at the bottom of your PR.
+
+This process serves as a check to help you understand the full impact of your changes. It will also save you time after you make a new release, because you can reuse the draft PRs later to complete upgrades.

docs/contributing.md

@@ -11,6 +11,7 @@
 - [Creating pull requests](#creating-pull-requests)
 - [Testing changes to packages in another project](#testing-changes-to-packages-in-another-project)
 - [Releasing changes](#releasing-changes)
+  - [Preparing and releasing breaking changes](./breaking-changes.md)
 - [Performing operations across the monorepo](#performing-operations-across-the-monorepo)
 - [Adding new packages to the monorepo](#adding-new-packages-to-the-monorepo)
 
@@ -201,6 +202,7 @@ Have changes that you need to release? There are a few things to understand:
 - The responsibility of maintenance is not the only thing shared among multiple teams at MetaMask; releases are as well. That means **if you work on a team that has codeownership over a package, you are free to create a new release without needing the Wallet Framework team to do so.**
 - 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.
+- Breaking changes take special consideration. [Read the guide](./breaking-changes.md) on how to prepare and handle them effectively.
 
 Now for the process itself, you have two options: using our interactive UI (recommended for most users) or manual specification.
 

docs/reviewing-release-prs.md

@@ -90,24 +90,9 @@ With that in mind, there are three ways changes can be categorized:
 
 ### Breaking changes
 
-A change is "breaking" if it is included in a version of a package, which, after a consumer upgrades to it and makes no further changes, causes one of the following:
-
-- An error at runtime
-- An error at compile time (e.g., a TypeScript type error)
-- An error at install time (e.g., the consumer's package manager reports a Node version incompatibility)
-- A surprising difference in behavior
-
-Given this, there are many ways a change could be regarded as breaking:
-
-- Changing a function or method to throw an error
-- Adding a required argument to a function or method
-- Adding a required property to a TypeScript type
-- Narrowing the type of a property in a TypeScript type
-- Narrowing the type of an argument in a function
-- Adding or removing a parameter to a TypeScript type
-- Upgrading a runtime dependency to a version which causes any of the above
-- Removing an export from the package
-- Bumping the minimum supported Node.js version
+A change is "breaking" if upgrading a project to a version containing the change would require modifications to source code or configuration in order to avoid user- or developer-facing problems (an inability to use or build the project, a loss of functionality, etc.).
+
+There are many kinds of breaking changes. You can find a list of examples [here](./breaking-changes.md#what-is-a-breaking-change).
 
 ### Additions