| name | personal-framework-release-blog |
| description | Drafts the "Framework" section of the Flutter release blog. Use when preparing release announcements to analyze commits, verify PR inclusion (including reverts/relands), and group changes into thematic narratives like Material/Cupertino updates, Web, and Accessibility. |
Personal Framework Release Blog
This skill guides the process of drafting the "What's New in the Framework" section for a Flutter release blog post. It focuses on creating a narrative of evolution rather than a simple list of changes.
Workflow
1. Setup and Theme Identification
Compare the previous stable tag (old_tag) to the new release tag (new_tag).
2. Iterative Drafting (Per Theme)
For each approved theme:
- Gather PRs: Find relevant PRs in the filtered commit log for that theme.
- Critically Analyze: Do not rely solely on initial PR titles and markdown descriptions (
gh pr view), which often contain outdated plans or TODOs. Inspect the actual landed commit summary and diff to verify exact signatures and behavior:
git log -1 --format=%B <commit_sha>
git show --stat <commit_sha>
git diff <commit_sha>^..<commit_sha> -- packages/flutter/lib/
- Verify Inclusion:
- Check release inclusion accurately across release candidate branches and cherry-picks using Flutter's official
find-release tool:
dart run engine/src/flutter/third_party/dart/tools/find_release.dart --commit=<SHA> --channel=stable
Alternatively, verify via git logs in the release range if the tool is unavailable:
git log <old_tag>..<RELEASE_TAG> --grep="cherry picked from commit <SHA>" || git merge-base --is-ancestor <SHA> <RELEASE_TAG>
- Check for reverts bounded strictly to the release range (
<old_tag>..<RELEASE_TAG>) to avoid false positives from post-release reverts on master. Search for both PR numbers and original commit SHAs:
git log <old_tag>..<RELEASE_TAG> -E --grep="Revert(s)?.*#<pr_number>" --grep="<original_commit_sha>"
- If reverted within the release range, check whether the reland PR merged before the release cutoff (
<RELEASE_TAG>).
- Draft Narrative: Group related changes into a cohesive story. Use sentence case for headers. Focus on why the change matters. For any featured PRs, check whether the author is not a member of the GitHub Googlers team (e.g., via commit author or
gh pr view) and actively look for opportunities to feature and credit community contributors by name in the narrative.
- Deduplication Check: Before appending any newly drafted section to the release document (
X-XX-release.md), cross-reference all PR numbers (#XXXXXX) against existing sections. If a PR or widget feature is already documented, remove or consolidate the duplicate mention into the most cohesive section.
3. Special Sections
- Deprecations and Breaking Changes:
- Strategic & Non-Commit Announcements: Ask the user if there are any high-level strategic announcements or non-commit-based initiatives (e.g., package unbundling or policy updates) that should be included in the release document before finalization.
4. Finalization
- Tone and Style: Ensure the draft matches the professional, engaging, and developer-focused tone of previous release blogs. See sample-blog.md for a reference implementation.
- Introduction & Summary: Write a compelling intro highlighting the "story" of the release, and conclude with the impact on the developer experience.
- Review: Perform a holistic check to ensure consistent tone, present tense, descriptive embedded links, and zero duplicate PR mentions across sections.
Principles
- Specific and Explicit: List affected widgets, classes, and APIs directly instead of using vague language.
- Inclusive Language: Avoid "we/our"; use "developers" or passive voice ("A feature is available").
- Embedded PR Links: Do not link PRs as standalone PR numbers (
[#123456](...)). Instead, embed the pull request link directly into the relevant descriptive text in the sentence (e.g., [Popup windows are now supported on Linux](https://github.com/flutter/flutter/pull/185866)). Always attribute changes to their pull request URL, not commit hashes.
- Feature Community Contributors: Actively look for opportunities to feature and credit external/community contributors by name for featured PRs when they are not members of the GitHub Googlers team.
- Avoid Signs of AI Writing: Strictly avoid formulaic patterns described in Wikipedia:Signs_of_AI_writing. Specifically:
- Do not use promotional puffery or AI vocabulary (
robust, seamless, elevate, unlocks the ability, empower, foundational, granular, streamline, resilient, paramount, tapestry, state-of-the-art, significantly, revolutionary).
- Do not write formulaic triples ("rule of three" grouping of adjectives, nouns, or verbs like
A, B, and C).
- Do not write generic introductory filler/topic sentences that state general truths (
Text selection is a core component..., Accessibility remains a primary focus...). Start paragraphs directly with concrete facts.
- Do not use negative parallelisms (
not only X, but also Y, not X, but Y, X rather than Y).
- Do not overuse em dashes (
—...—) or dramatic copulatives/verbs (serves as, stands as, remains a primary focus). Use plain verbs (is, are, adds, updates, supports, fixes).
- Narrative over Lists: Weave updates into a compelling story explaining why changes matter without relying on AI clichés.
- Sentence Case Headers: All headings and subheadings must use sentence case (e.g., "Material and Cupertino updates"), not title case.
