Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/update-changelog

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

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.

  • 1 file
  • 9.9 KB
  • Updated last week
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/update-changelog

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈83 tokens for metadata: the name and description. ≈2.4k when used: this file.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈332 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  • Swift package (swift/CHANGELOG.md):
    • All four library products in root Package.swift (A2UISwiftCore, A2UISwiftUI, BasicCatalog, and BasicCatalogSwiftUI) share swift/CHANGELOG.md. Follow the core rules below, wrap lines at 100 characters (swift/CODING_STANDARDS.md), and exclude changes confined to swift/sample/ or test targets.
  • 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, swift/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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/update-changelog