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, 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.
• 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

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

## 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)

## 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.

2. Retrieve Current PR Number:

   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:

   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).

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:

   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:

   ./scripts/fix_format.sh