---
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:

```
Changelog 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:

````markdown
### [Component] Brief description

Explanation of what changed.

**Migration:**

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

**Impact**: Effect on existing code.

````

**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}:**

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

**Migration**: How to migrate.

````

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

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

Description of the feature.

```

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