| name | update-changelog |
| description | Update ai-projects CHANGELOG.md after a TypeSpec regeneration. Merges new items into the existing top (Unreleased) entry when present; otherwise creates a new top entry, classifying changes into Breaking Changes / Features Added / Bugs Fixed / Other Changes buckets and syncing package.json version as needed. |
Update CHANGELOG.md for an ai-projects regeneration
When to Use
- The
apply-post-emitter-edits, author-samples, and author-tests skills have all completed.
- A regeneration has produced a meaningful diff in
src/ and review/ai-projects-node.api.md.
- You need a CHANGELOG entry before opening the PR.
Inputs
Procedure
Run from sdk/ai/ai-projects/.
Step 1: Read the current CHANGELOG style
Open CHANGELOG.md. Note the section ordering used in recent entries:
### Breaking Changes### Features Added### Bugs Fixed### Other Changes
Voice examples (copy this voice exactly):
- Features: "Add
project.beta.skills route for accessing skills"
- Breaking: "Rename
id property in Schedule interface to schedule_id"
- Bugs: "Remove redundant
foundryFeatures property from EvaluationRulesCreateOrUpdateOptionalParam"
- Other: "Deprecated
TextResponseFormatConfiguration in favor of TextResponseFormat"
Step 2: Classify changes
For each item from the api-surface diff plus each hand-applied edit:
| Bucket | What goes here |
|---|
| Breaking Changes | Removed/renamed public symbols; required→optional or optional→required; method signature changes; namespace renames. |
| Features Added | New public classes, methods, namespaces, interfaces. |
| Bugs Fixed | Behavioral fixes; redundant-property removals; correctness fixes from post-emitter workarounds. |
| Other Changes | Deprecations, internal refactors, dependency bumps. |
Beta-namespace additions still go under Features Added, with the namespace path included (e.g., project.beta.toolboxes).
When a new public method or route brings supporting request/response models, helper classes, union members, or enum values along with it, do not enumerate every supporting type in the changelog. List the new public method/route and mention the feature it enables. Only call out supporting types separately when they are independently user-facing concepts that customers would reasonably search for outside the method they support.
Step 3: Insert or extend the top entry
First, inspect the current top entry in CHANGELOG.md:
- If it is already an
## <version> (Unreleased) (or otherwise unreleased) entry, do not create a new entry and do not bump the version. Instead, merge the new items into the existing buckets under that entry — adding new bullets, keeping the existing ones, and dropping any subsection that ends up empty. Skip Step 3.5 entirely in this case (the package.json version already matches).
- Only if the current top entry is a released version (i.e. its header has a date, not
(Unreleased)) do you create a new top entry. Use templates/changelog-entry.md and insert it directly above that released entry.
When creating a new entry, pick a tentative next version following semver against the previous CHANGELOG entry:
- Breaking Changes present → bump major (e.g.,
2.1.0 → 3.0.0).
- Features Added only → bump minor (e.g.,
2.1.0 → 2.2.0).
- Bugs Fixed / Other Changes only → bump patch (e.g.,
2.1.0 → 2.1.1).
Use the header form ## <new-version> (Unreleased) so the release engineer just has to swap Unreleased for a date.
Drop empty subsections (don't leave a ### Bugs Fixed heading with no items underneath).
Step 3.5: Sync package.json version
Skip this step if you merged into an existing (Unreleased) entry in Step 3 — the version did not change, so package.json is already correct.
When you created a new top entry, the version field in package.json MUST match the version in that new entry. Update package.json to match (e.g., "version": "2.2.0"). Release tooling fails CI if these drift.
Step 4: Validate
- The CHANGELOG still parses (
npx prettier --check CHANGELOG.md).
- No duplicate items across buckets.
- Each line is a single bullet starting with a verb in the same tense as nearby entries.
package.json version field matches the top CHANGELOG entry's version (run node -p "require('./package.json').version" and compare).
Hand-off
Done. Hand off to open-regeneration-pr.
