write-changelog-entry

name	write-changelog-entry
description	Use when asked to add, revise, or review a changelog or release-notes entry in this repo. Inspect the existing changelog section style and the relevant PR, issue, and commit context first, then write a focused entry in the correct release section without overstating docs, tests, or chores unless they are the primary user-facing change.

Purpose

Write changelog entries that match the surrounding section's style and reflect the actual shipped change for the intended audience.

Inputs

• Target changelog file, if specified; otherwise infer it from the changed package and audience.
• Release version or section if the user specifies one.
• Relevant PR number, issue number, commit(s), or branch context.

Target file selection

Choose the narrowest correct changelog file before writing entries.

• Use /CHANGELOG.md for repo-level or broadly user-facing Flet changes.
• Use packages/flet/CHANGELOG.md only for changes relevant to Flutter package consumers and extension developers. See the dedicated section below.
• Use sdk/python/packages/<package>/CHANGELOG.md for changes scoped to a specific Python package.
• For extension (ex: flet-audio) changelogs under sdk/python/packages/<package>/CHANGELOG.md, write entries from the published Python user's perspective. Do not surface internal Flutter implementation changes unless they materially change the Python-facing feature, behavior, or API.
• If one change clearly belongs in more than one published surface, update each relevant changelog file.
• Do not default everything to /CHANGELOG.md when a package-specific changelog is the better fit.

Root vs Flutter package changelog

/CHANGELOG.md and packages/flet/CHANGELOG.md have different audiences.

• /CHANGELOG.md is the broad Flet product changelog. Write entries from the app developer's perspective, usually summarizing the shipped feature or fix at about PR-title specificity.
• packages/flet/CHANGELOG.md is for Flutter package consumers and extension developers. Write entries only when they need to know a specific Dart-side API, utility, parser, serializer, runtime contract, dependency, or compatibility change.
• Do not repeat a root changelog entry in packages/flet/CHANGELOG.md merely because the implementation touched Dart files.
• If both audiences are affected, update both changelogs, but phrase them differently: the root entry should describe the user-facing outcome, while the Flutter package entry should describe the precise Dart/extension-facing change.

Example split:

• Root: Add support for text-or-control labels in \NavigationDestination`s.`
• Flutter package, only if applicable: Extend \Control` with `.buildTextOrWidget()` to parse properties that accept either plain text or child controls.`

Workflow

1. Inspect the target changelog section before editing.
   • Match the existing headings and item style exactly.
   • In this repo, preferred buckets are:
     • ### New features
     • ### Improvements
     • ### Bug fixes
     • ### Documentation
     • ### Other changes
2. Inspect the source of truth for scope and audience.
   • Prefer PR title and PR description/summary over commit noise.
   • Use linked issues to understand user-facing intent.
   • Use commits only to confirm details or fill gaps.
3. Extract the primary shipped change.
   • Lead with the API, control, command, or behavior that changed.
   • Mention docs, examples, tests, refactors, or chores only when they are the main outcome the changelog audience would care about.
4. Write concise item(s) for the selected changelog(s).
   • Avoid laundry lists unless the PR truly shipped multiple peer-level features.
   • Prefer concrete nouns and verbs over implementation detail.
   • Keep each sentence focused on what that changelog's audience gained or must know.
5. Add links and attribution in repo style.
   • Include both related issue link(s) and PR link(s) when available, with issue links first.
   • If no issue exists, include PR link(s) only.
   • Include issue-only direct-commit items when a shipped change has no PR.
   • Use plain-text author attribution at the end: by @login.
   • Use the PR author login for PR-based items.
   • For issue-only direct-commit items, use the commit author login if available.
   • If one item groups multiple PRs by different authors, attribute all relevant authors: by @user1, @user2.

Repo-specific guidance

• Do not mention tests in changelog items unless the change itself is test infrastructure.
• Use ### Documentation for docs website, CrocoDocs, generated API reference, examples, guides, or docs tooling changes when documentation is the primary deliverable.
• Do not mention docs/examples in other sections unless documentation is the primary deliverable.
• Avoid words like refactor, cleanup, or coverage unless the section is Other changes and that is truly the point.
• If a PR includes one main feature plus supporting docs/tests, write only the main feature.
• If a PR title is too narrow or too broad, use the PR description and diff to calibrate the final wording.
• If an item touches multiple controls, only group them when the change is one coherent feature.
• Do not add chore, trivial, or duplicate items to user-facing release notes.
• For extension package changelogs, prefer Python-facing API, behavior, packaging, and usability changes over Flutter implementation details that are not directly published to users.

Good patterns

Root changelog:

• * Add \scrollable` to `NavigationRail` for overflowed destinations (#1923, #6356) by @login.`
• * Make \NavigationDrawerDestination.label` accept custom controls and add `NavigationDrawerTheme.icon_theme` (#6379, #6395) by @login.`

Flutter package changelog:

• * Improve \parseBool()` to accept string and numeric payload values (#1234) by @login.`
• * Extend \Control` with `.buildTextOrWidget()` to parse properties that accept either strings or child controls (#1234) by @login.`
• * Improve extension asset resolution to avoid package path collisions ([#1234](...)) by @login.
• * Add \parseEnum()` utility for consistent enum parsing (#1234) by @login.`

Checks

Before finishing, verify:

• The item sits under the right release and section.
• The wording matches neighboring entries in length and tone.
• The sentence describes the primary change for that changelog's audience.
• packages/flet/CHANGELOG.md entries are specific to Dart/Flutter package or extension-facing behavior and are not bare repeats of root changelog entries.
• Issue and PR links follow repo style, including issue-only direct-commit cases.
• Attribution is plain text and placed last.