Release Note Writer

Release Note Writer

Core Rule

Write release notes in English only. Convert technical history into reader-facing changes grouped by audience and outcome. Do not mirror commit scopes directly.

Required Discovery

Before drafting, gather the release context:

1. Check the current repo version and tags.
   • Inspect package/version files that already exist in the repo.
   • Inspect recent git tags with git tag --sort=-v:refname.
   • Identify the previous release tag.
2. Run changelogithub dry output:
   • pnpm dlx changelogithub --dry --from <previous-version>
   • If the command needs network and fails because of sandboxing, request approval and rerun it.
3. Inspect the generated commit structure and then inspect commits directly.
   • Use git show --stat --oneline <sha> or equivalent targeted commands.
   • Include chore/internal commits when they affect contributor workflow, tooling, builds, CI, local development, docs generation, test infrastructure, or internal packages.
4. If version boundaries are ambiguous, ask one concise question before drafting.

Audience Structure

Use a compact, aggregated structure. Prefer fewer major sections with useful subheadings over many small scope-based sections. Use multiple heading levels when that makes the audience or product surface clearer.

Recommended order:

1. Product-facing sections for end users.
2. ### To developers near the end.
3. ### To contributors last.
4. ### Upgrade notes only when action is required.

Product-facing sections can be nested by surface:

• ### Product updates
• #### Local
• #### Cloud
• #### New providers
• #### Chat and settings

Do not force every release into these exact headings. Pick headings that make the release easy to scan.

Use a dedicated bug-fix section when fixes include critical regressions, blocked primary workflows, or issues users may scan the notes to confirm. Critical bugs deserve plain, concrete language because users may be checking whether their blocker was fixed. Minor visual, wording, and low-impact cleanup can stay grouped as polish, but do not bury important fixes inside broad product updates.

Use To developers for external developer impact:

• Plugin SDK, plugin manifest, gamelet, widget, extension, public package API, self-host deployment behavior, server-runtime, Docker image behavior, integration contracts.
• Include deployment behavior changes that affect external operators.
• Do not include purely internal server/apps/api business logic unless users of AIRI Cloud or external operators need to act on it.

Use To contributors for internal project work:

• vishot, cap-vite, CI, dev scripts, repo build/test/lint workflow, docs generation, internal-only packages, release automation, test harnesses, screenshots, evaluation tools.
• Include relevant chore commits even when changelogithub does not surface them prominently.

End-User Writing

For UI, apps/stage-*, packages/stage-*, and packages/ui changes, emphasize what the user can now do and what annoyance was removed.

Use patterns like:

• "You can now ..."
• "Previously, ... could ... . We fixed this so ..."
• "We added ... to help you ..."
• "Some ... cases could ... . We cleaned this up so ..."

Avoid exposing implementation names unless they are user-visible product names or provider names. Keep technical terms out of end-user sections when a plain description works.

Release notes should speak from the user's experience, not from the implementation. For fixes, write what the user saw, what workflow was blocked or degraded, and what now works. Do not describe internal causes such as lifecycle order, handler registration, IPC timing, stale stores, or runtime plumbing unless the term is part of the user-facing product. Critical fixes should be plain and concrete, not softened into vague polish.

If commit titles, diffs, tests, and surrounding files do not make the user-facing effect clear, do not invent one. Ask the user one concise question about what happened and how it affected users before drafting that bullet.

Good:

• "You can now retry a failed message directly from the chat."
• "Some provider lists were hard to reach on smaller screens. They now scroll correctly."

Avoid:

• "Refactored stage-ui chat action menu state."
• "Fixed provider list CSS overflow in stage-pages."

Provider Section

Create a provider section when provider changes exist. Keep it concise and grouped by capability. Prefer placing it under a product-facing parent when the release has multiple product surfaces, for example ### Product updates -> #### Local -> ##### New providers.

Example:

### Product updates

#### Local

##### New providers

- You can now use Amazon Bedrock as a chat provider.
- You can now use MiniMax Speech as a TTS provider.
- Artistry now supports image providers such as ComfyUI, Replicate, and Nano Banana.