## **Description**

This PR adds comprehensive release workflow documentation for AI agents
and human maintainers, addressing a critical gap in MIGRATION.md
documentation guidance.

**What changed:**

1. **Created `.cursor/rules/release-workflow.md`** (244 lines - Layer 2
cursor rule):
- Step-by-step release creation workflow (`yarn create-release-branch`)
- Release strategy guidance (release often, isolate large breaking
changes)
- Changelog quality standards with **explicit rules to remove dev
dependencies**
- **MIGRATION.md documentation patterns** (structure, critical rules,
examples) - NEW
- **Peer dependency warning** - do NOT manually update (causes build
errors)
   - PR template usage and release PR structure
   - Verification checklists for release quality
   - Anti-patterns with before/after examples

2. **Updated `docs/reviewing-release-prs.md`**:
   - Added new **Section 7: Review MIGRATION.md for breaking changes**
   - Updated tl;dr checklist to include MIGRATION.md verification
- Cross-references `.cursor/rules/release-workflow.md` for detailed
examples

3. **Created `.github/PULL_REQUEST_TEMPLATE/release.md`**:
   - Standardized release PR template based on recent releases (PR #972)
- Structured sections: package versions, categorized changes, breaking
changes
   - Pre-filled verification checklist
   - Usage: append `?template=release.md` to PR compare URL

4. **Updated `CLAUDE.md`**:
   - Added reference to new release-workflow rule

**Why these changes:**

During the v25 release, we identified that there was no guidance on:
- How to write MIGRATION.md documentation for breaking changes
- When to update MIGRATION.md (any breaking change)
- What structure/examples to use in migration sections
- Critical rules (realistic examples, table of contents updates,
before/after code)
- **What to exclude from changelogs** (dev dependencies, internal
tooling)
- **Peer dependency management** (automated by yarn workspaces)

This PR fills those gaps with AI-first documentation following our
three-layer strategy (see docs/ai-agents.md):
- Layer 1 (CLAUDE.md): References new rule
- Layer 2 (.cursor/rules/): Actionable checklist-based workflow (200-400
lines)
- Layer 3 (docs/): Human-focused reviewer guide now includes
MIGRATION.md verification

**Key improvements from review feedback:**

1. ✅ Release strategy: Isolate large breaking changes to single releases
2. ✅ Command corrected: `yarn create-release-branch` (not npx)
3. ✅ Changelog quality: Remove dev dependencies and developer-only
changes
4. ✅ Peer deps: Critical warning not to manually update (causes errors)
5. ✅ Golden paths: Both React and React Native MIGRATION.md references
6. ✅ Trimmed: 244 lines (within 200-400 target range)
7. ✅ Removed editorial: "(Critical Gap)" from heading

**MIGRATION.md structure documented:**

\`\`\`markdown
## From version 0.X.0 to 0.Y.0

### Component Breaking Change

**What Changed:**
- Old vs new API
- Rationale

**Migration:**
\\\`\\\`\\\`tsx
// Before (0.X.0)
import { Component } from '@metamask/design-system-react';
<Component oldProp={value} />

// After (0.Y.0)
import { Component, NewEnum } from '@metamask/design-system-react';
<Component newProp={NewEnum.Value} />
\\\`\\\`\\\`

**Impact:**
- Who is affected
- What breaks
\`\`\`

## **Related issues**

Fixes: N/A (Documentation improvement identified during v25 release)

## **Manual testing steps**

1. Review \`.cursor/rules/release-workflow.md\` for completeness
2. Check MIGRATION.md guidance section matches recent v25 patterns
3. Verify release PR template structure matches PR #972
4. Confirm CLAUDE.md correctly references new rule
5. Review \`docs/reviewing-release-prs.md\` new section 7

## **Screenshots/Recordings**

N/A - Documentation only

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable (N/A - documentation)
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable (N/A - markdown docs)
- [ ] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation/template additions only; no runtime or build logic
changes, so risk is limited to process adoption/accuracy.
> 
> **Overview**
> Adds an AI-focused release workflow rule
(`.cursor/rules/release-workflow.md`) that standardizes release branch
creation, dependency update commands, changelog quality expectations,
and required `MIGRATION.md` documentation for breaking changes
(including anti-pattern callouts).
> 
> Introduces a dedicated release PR template
(`.github/PULL_REQUEST_TEMPLATE/release.md`) with sections for
package/version listings, platform-specific changes, explicit
breaking-change migration guidance, and pre-merge checklists; updates
`docs/reviewing-release-prs.md` to require reviewing `MIGRATION.md` for
breaking changes and links this guidance from `CLAUDE.md`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e648a38. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

## **Description**

This PR adds comprehensive release workflow documentation for AI agents
and human maintainers, addressing a critical gap in MIGRATION.md
documentation guidance.

**What changed:**

1. **Created `.cursor/rules/release-workflow.md`** (244 lines - Layer 2
cursor rule):
- Step-by-step release creation workflow (`yarn create-release-branch`)
- Release strategy guidance (release often, isolate large breaking
changes)
- Changelog quality standards with **explicit rules to remove dev
dependencies**
- **MIGRATION.md documentation patterns** (structure, critical rules,
examples) - NEW
- **Peer dependency warning** - do NOT manually update (causes build
errors)
   - PR template usage and release PR structure
   - Verification checklists for release quality
   - Anti-patterns with before/after examples

2. **Updated `docs/reviewing-release-prs.md`**:
   - Added new **Section 7: Review MIGRATION.md for breaking changes**
   - Updated tl;dr checklist to include MIGRATION.md verification
- Cross-references `.cursor/rules/release-workflow.md` for detailed
examples

3. **Created `.github/PULL_REQUEST_TEMPLATE/release.md`**:
   - Standardized release PR template based on recent releases (PR #972)
- Structured sections: package versions, categorized changes, breaking
changes
   - Pre-filled verification checklist
   - Usage: append `?template=release.md` to PR compare URL

4. **Updated `CLAUDE.md`**:
   - Added reference to new release-workflow rule

**Why these changes:**

During the v25 release, we identified that there was no guidance on:
- How to write MIGRATION.md documentation for breaking changes
- When to update MIGRATION.md (any breaking change)
- What structure/examples to use in migration sections
- Critical rules (realistic examples, table of contents updates,
before/after code)
- **What to exclude from changelogs** (dev dependencies, internal
tooling)
- **Peer dependency management** (automated by yarn workspaces)

This PR fills those gaps with AI-first documentation following our
three-layer strategy (see docs/ai-agents.md):
- Layer 1 (CLAUDE.md): References new rule
- Layer 2 (.cursor/rules/): Actionable checklist-based workflow (200-400
lines)
- Layer 3 (docs/): Human-focused reviewer guide now includes
MIGRATION.md verification

**Key improvements from review feedback:**

1. ✅ Release strategy: Isolate large breaking changes to single releases
2. ✅ Command corrected: `yarn create-release-branch` (not npx)
3. ✅ Changelog quality: Remove dev dependencies and developer-only
changes
4. ✅ Peer deps: Critical warning not to manually update (causes errors)
5. ✅ Golden paths: Both React and React Native MIGRATION.md references
6. ✅ Trimmed: 244 lines (within 200-400 target range)
7. ✅ Removed editorial: "(Critical Gap)" from heading

**MIGRATION.md structure documented:**

\`\`\`markdown
## From version 0.X.0 to 0.Y.0

### Component Breaking Change

**What Changed:**
- Old vs new API
- Rationale

**Migration:**
\\\`\\\`\\\`tsx
// Before (0.X.0)
import { Component } from '@metamask/design-system-react';
<Component oldProp={value} />

// After (0.Y.0)
import { Component, NewEnum } from '@metamask/design-system-react';
<Component newProp={NewEnum.Value} />
\\\`\\\`\\\`

**Impact:**
- Who is affected
- What breaks
\`\`\`

## **Related issues**

Fixes: N/A (Documentation improvement identified during v25 release)

## **Manual testing steps**

1. Review \`.cursor/rules/release-workflow.md\` for completeness
2. Check MIGRATION.md guidance section matches recent v25 patterns
3. Verify release PR template structure matches PR #972
4. Confirm CLAUDE.md correctly references new rule
5. Review \`docs/reviewing-release-prs.md\` new section 7

## **Screenshots/Recordings**

N/A - Documentation only

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable (N/A - documentation)
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable (N/A - markdown docs)
- [ ] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation/template additions only; no runtime or build logic
changes, so risk is limited to process adoption/accuracy.
> 
> **Overview**
> Adds an AI-focused release workflow rule
(`.cursor/rules/release-workflow.md`) that standardizes release branch
creation, dependency update commands, changelog quality expectations,
and required `MIGRATION.md` documentation for breaking changes
(including anti-pattern callouts).
> 
> Introduces a dedicated release PR template
(`.github/PULL_REQUEST_TEMPLATE/release.md`) with sections for
package/version listings, platform-specific changes, explicit
breaking-change migration guidance, and pre-merge checklists; updates
`docs/reviewing-release-prs.md` to require reviewing `MIGRATION.md` for
breaking changes and links this guidance from `CLAUDE.md`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e648a38. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->