---

name: updating-changelog description: Updates changelog documentation for contract developers and node operators by analyzing branch changes relative to 'next'. Use when preparing a PR, updating migration notes, documenting breaking changes, or when asked to update changelog/release notes.

Updating Changelog

Workflow

Copy this checklist and track progress:

CopyChangelog Update Progress:
- [ ] Step 1: Determine target changelog file from .release-please-manifest.json
- [ ] Step 2: Analyze branch changes (git diff next...HEAD)
- [ ] Step 3: Generate draft entries for review
- [ ] Step 4: Edit documentation files after approval

Step 1: Determine Target Files

Read .release-please-manifest.json to get the version (e.g., {"." : "4.0.0"} → edit v4.md).

Target files:

• Aztec contract developers: docs/docs-developers/docs/resources/migration_notes.md
• Node operators and Ethereum contract developers: docs/docs-network/reference/changelog/v{major}.md

Step 2: Analyze Branch Changes

Run git diff next...HEAD --stat for overview, then git diff next...HEAD for details.

Categorize changes:

• Breaking changes (API modifications, removals, renames)
• New features (APIs, CLI flags, configuration)
• Deprecations
• Configuration changes (CLI flags, environment variables)

Step 3: Generate Draft Entries

Present draft entries for review BEFORE editing files. Match the formatting conventions by reading existing entries in each file.

Step 4: Edit Documentation

After approval, add entries to the appropriate files.

Migration Notes Format

File: docs/docs-developers/docs/resources/migration_notes.md

Add entries under ## TBD section:

Copy### [Component] Brief description

Explanation of what changed.

**Migration:**

```diff
- old code
+ new code
```

Impact: Effect on existing code.

Copy
**Component tags:** `[Aztec.nr]`, `[Aztec.js]`, `[PXE]`, `[Aztec Node]`, `[AVM]`, `[L1 Contracts]`, `[CLI]`

## Node Operator Changelog Format

**File:** `docs/docs-network/reference/changelog/v{major}.md`

**Breaking changes:**
```markdown
### Feature Name

**v{previous}:**
```bash
--old-flag <value>                    ($OLD_ENV_VAR)

v{current}:

Copy--new-flag <value>                    ($NEW_ENV_VAR)

Migration: How to migrate.

Copy
**New features:**
```markdown
### Feature Name

```bash
--new-flag <value>                    ($ENV_VAR)

Description of the feature.

Copy
**Changed defaults:** Use table format with Flag, Environment Variable, Previous, New columns.