update-changelog

---
name: update-changelog
description: >-
  Instructions and best practices for updating CHANGELOG.md files across A2UI packages. Use when
  adding or modifying a CHANGELOG.md file, when a PR adds, modifies, deprecates, or removes public
  exports or consumer-observable behavior in a published package, or when resolving merge conflicts
  in a CHANGELOG.md file.
---

# Updating Changelogs (`CHANGELOG.md`)

## Progressive Discoverability: Language-Specific Routing

Before editing a `CHANGELOG.md` file, check which language directory the modified package belongs to:

- **Dart / Flutter packages (`dart/*/CHANGELOG.md`)**:
  - Load and follow [`dart/versioning-and-releases.md`](../coding-principles/subskills/dart/versioning-and-releases.md), which defines Dart-specific `Breaking:` annotations, `## Unreleased` consolidation rules, and `pubspec.yaml` versioning conventions.
- **Python packages (`python/*/CHANGELOG.md`)**:
  - Follow the core rules below for `## Unreleased` entries during feature or bugfix PRs. When cutting a Python package release, load [`a2ui-release-python`](../a2ui-release-python/SKILL.md).
- **TypeScript / Web packages (`typescript/*/*/CHANGELOG.md`)**:
  - Follow all core rules, formatting conventions, and workflows in this document.

---

## Core Rules

1. **Preserve Unrelated Entries and All Version Headers**:

   > [!CAUTION]
   > **Preserve Unrelated Entries**: NEVER delete, overwrite, or clear unrelated items under `## Unreleased` or any items under past release sections. Other merged branches, concurrent PRs, or foundational commits have their own entries under `## Unreleased`. However, read the entire `## Unreleased` section before adding your entry: if your PR supersedes, renames, or modifies a change introduced earlier in the same `## Unreleased` cycle, update or merge that unreleased entry so `## Unreleased` describes the net changes since the last published release rather than a chronological log of contradicting pull requests. When merging, keep every PR link the merged entries carried (for example `[#123](...), [#456](...)`) so each change stays traceable to its pull request.

   > [!CAUTION]
   > **Preserve All Version Headers**: NEVER delete a `## <version>` heading (for example `## 0.10.6`). Removing one moves every entry beneath it into the section above, so released changes reappear as unreleased and that version's history is lost. This most often happens while resolving a merge conflict at the top of the file, or when inserting an entry overwrites the lines that follow `## Unreleased`. After any conflict resolution, re-read the top of the file and confirm the version headers are still present and in descending order.

2. **Always Target the `## Unreleased` Section**:
   - Place every new changelog entry under the top-level `## Unreleased` heading at the top of the modified package's `CHANGELOG.md` file.
   - If the `## Unreleased` heading does not exist, create it at the top of the file before the latest released version.
   - Never create or bump a version header (e.g. `## 0.10.6`) during feature or bugfix development unless explicitly executing a release workflow.

3. **Focus Exclusively on Public API Surface Changes**:
   - **DO Document**:
     - New or modified public exports, classes, functions, components, directives, traits, or services.
     - Additions, removals, or changes to component schemas, properties, inputs, outputs, or events.
     - Bug fixes that alter consumer-facing behavior, rendering output, or public type definitions.
     - Dependency changes affecting consumers (e.g. optional peer dependencies).
     - Breaking changes (marked prominently with `**BREAKING CHANGE**:`).
   - **DO NOT Document**:
     - Internal implementation details, classes, algorithms, data structures, or mechanics (e.g. private helper functions, internal variable renames, internal state/undo-log mechanics, micro-optimizations, or narrations of how the previous implementation worked).
     - Changes strictly confined to unit tests, integration tests, conformance suite filenames, benchmark numbers, mock data, sample/explorer applications, or internal scripts.
     - Pure refactorings that preserve identical public API behavior and types.

4. **Clearly Annotate and Group BREAKING CHANGE Entries First**:

   > [!IMPORTANT]
   > **Mandatory `**BREAKING CHANGE**:` Annotation and Ordering**:
   > Place all `**BREAKING CHANGE**:` entries at the **top** of the `## Unreleased` section, with non-breaking additions and fixes below them. Annotate entries with `**BREAKING CHANGE**:` whenever there is:
   >
   > 1. **Public API Surface Change**: Any removal, rename, or incompatible signature/type change in the public API surface of the library or package (e.g., exported functions, classes, interfaces, component schemas, properties, signatures, or public types).
   > 2. **Meaningful Behavioral Change**: Any meaningful change in behavior that is not purely an internal refactor (e.g., changes to default property values, alterations to DOM tree structure or class names, changes to CSS custom properties or styling inheritance contracts that consumers depend on, modifications to validation rules, or changes to event dispatch semantics).
   >
   > Provide a concise explanation of what changed, why, and a recommended migration note so consumers can upgrade cleanly.

5. **Be Concise and Complete**:
   - Keep each entry to one or two sentences stating _what_ changed and _how_ callers should update their code. Do not narrate why the previous implementation worked the way it did.
   - Prefix version-specific changes with the target protocol version (e.g. `(v0_9)` or `(v0_8)`) when working within multi-version renderers or packages.
   - If a breaking change is introduced, provide a brief migration note.

6. **Always End Entries with a Link to the PR**:
   - Conclude each entry with a clickable link to its associated GitHub Pull Request:
     `[#<pr-number>](https://github.com/a2ui-project/a2ui/pull/<pr-number>)`

---

## Format & Examples (TypeScript / Web & Python)

### Single Feature or Bug Fix

```markdown
## Unreleased

- (v0_9) Add universal markdown fallback in `Text` component when optional `@a2ui/markdown-it` is available. [#2272](https://github.com/a2ui-project/a2ui/pull/2272)
- (v0_9) Fix null de-referencing TypeError in `ComponentBinder` when `children` property is null or undefined. [#1472](https://github.com/a2ui-project/a2ui/pull/1472)
```

### Multi-Item Feature Group

```markdown
## Unreleased

- (v0_9) Support universal Web Components in the v0.9 renderer:
  - Add `UniversalBasicCatalog`, `NativeBasicCatalog`, and `BasicCatalogBase` supporting both universal Web Components from `@a2ui/web_core` and native Angular `@Component` implementations.
  - Add `toWebComponent` adapter to convert custom Angular `@Component` implementations into W3C Custom Elements.
  - Add standalone `provideA2Ui` configuration helper and `A2UI_USE_UNIVERSAL_COMPONENTS` injection token for Angular applications. [#2273](https://github.com/a2ui-project/a2ui/pull/2273)
```

### Breaking Changes (Public API Surface & Meaningful Behavioral Changes)

```markdown
## Unreleased

- **BREAKING CHANGE**: `BoundProperty.raw` is now `unknown` instead of `any`. Recommended migration: replace `raw` access with typed sibling fields where available (e.g. use `template` instead of `raw.componentId`/`raw.path`). [#1312](https://github.com/a2ui-project/a2ui/pull/1312)
- **BREAKING CHANGE**: (v0_9) `Image` component now defaults `fit` to `"cover"` (previously `"fill"`) to match responsive catalog container layouts. Recommended migration: explicitly set `fit: "fill"` if previous stretching behavior is required. [#2205](https://github.com/a2ui-project/a2ui/pull/2205)
```

---

## Step-by-Step Workflow

1. **Identify Affected Packages**:
   Find the `CHANGELOG.md` in the root of each published package modified in the PR (e.g. `typescript/core/web_core/CHANGELOG.md`, `typescript/renderers/angular/CHANGELOG.md`, `typescript/renderers/lit/CHANGELOG.md`, `typescript/renderers/react/CHANGELOG.md`, `dart/a2ui_core/CHANGELOG.md`). If modifying a Dart package under `dart/`, follow [`dart/versioning-and-releases.md`](../coding-principles/subskills/dart/versioning-and-releases.md).

2. **Retrieve Current PR Number**:

   ```bash
   gh pr view --json number --jq '.number'
   ```

3. **Check for Public API Surface or Meaningful Behavioral Changes**:
   Review `git diff` on exported symbols, types, components, schemas, defaults, and rendering behaviors:

   ```bash
   git diff main --stat
   ```

   Determine whether the diff introduces a public API change or a meaningful change in behavior that requires a `**BREAKING CHANGE**:` annotation (or `Breaking:` for Dart packages). For TypeScript packages, see [Inspecting TypeScript Public API (AST Approach)](../coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md).

4. **Add or Update the `## Unreleased` Entry**:
   Draft concise, complete descriptions following the core rules above, placing `**BREAKING CHANGE**:` entries at the top of `## Unreleased` and non-breaking entries below them, and append `[#<pr-number>](https://github.com/a2ui-project/a2ui/pull/<pr-number>)`.

5. **Verify No Unrelated Entries or Version Headers Were Removed**:

   ```bash
   git diff main -- '**/CHANGELOG.md' | grep '^-' | grep -v '^---'
   ```

   The only acceptable output is a revision or consolidation of an `## Unreleased` entry modified or superseded by the current PR. Any deleted version header or unrelated pre-existing entry must be restored immediately.

6. **Format the Repository**:
   ```bash
   ./scripts/fix_format.sh
   ```