changelog

Changelog

Translate a clearly defined change range into truthful release communication. Let the amount and importance of shipped work determine the item count, technical depth, and visual format.

Establish scope

Infer from the request and repository:

• target branch, tag range, release, or date window;
• whether uncommitted or unreleased work is excluded;
• audience and expected technical depth;
• output: prose, Markdown, HTML card, image, or a combination;
• existing changelog policy, template, visual system, and prior examples.

Ask only when the range or release status remains ambiguous. Record the exact range in the handoff. Do not describe merged, committed, or feature-flagged work as live without deployment evidence.

Inspect what changed

Start with repository-native release tooling when present. Otherwise inspect the chosen range:

git log --oneline <range>
git diff --stat <range>
git diff --name-status <range>

Read unclear diffs and relevant tests or documentation. Group commits by user-visible behavior rather than commit boundaries.

Include internal changes when they affect compatibility, security, reliability, performance, migration, or operator behavior. Exclude churn that has no consequence for the intended audience.

For each candidate item, capture:

• user or operator impact;
• evidence commits or diff paths;
• release status;
• breaking, migration, security, or limitation details;
• confidence and any missing deployment evidence.

Draft for the audience

Use as many items as the range supports. Combine changes only when they form one coherent outcome; do not pad the update to fill a layout.

Each item should answer what changed and why the audience cares. Include implementation language when readers need it to adopt, debug, migrate, or evaluate the release.

Preserve the product's voice and capitalization. Do not force lowercase, emoji, slogans, or benefit-only language. If icons or category labels are part of an existing template, use them consistently and accessibly.