# Update Whats New

> Update the whats-new page with changes to the website since the previous release.

- Skill: `dart-lang/update-whats-new` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dart-lang/update-whats-new`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dart-lang/update-whats-new/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dart-lang (https://skillmd.com/u/dart-lang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dart-lang/update-whats-new

---


# Update what's new page

Use this skill when a new Dart release has occurred and
you need to update `src/content/resources/whats-new.md`
to describe the changes to the website
since the previous release.

## Steps

1.  **Identify the previous release date**

    Read `src/content/resources/whats-new.md`
    and locate the topmost release section.
    Find the "Released on" date for that release.
    This is your starting point.

2.  **Retrieve recent Git commits**

    Retrieve the git commits made to the repository
    since the previous release date identified in step 1.
    For example:
    `git log --after="<previous_release_date>" --oneline`.

3.  **Analyze commits for meaningful changes**

    Review the content of each commit since that date.
    Identify changes that are significant to developers or users.
    Look for:

    -   New glossary terms.
    -   Large or significant page updates.
    -   New pages.
    -   Deprecated or removed pages.
    -   New tutorials or guide enhancements.

    > [!IMPORTANT]
    > When analyzing changes for the
    > "Site improvements" section,
    > ONLY include entries that are meaningful and
    > user-facing to someone reading our documentation.
    >
    > **Do NOT include:**
    > - Non-user-facing infrastructure changes,
    >   such as "Inlined card content on the docs index page".
    > - Internal refactoring or maintenance simplifications.
    > - Minor tweaks that aren't relevant to
    >   the broader documentation experience, such as
    >   "Surfaced lint release versions" or
    >   "Made heading anchors copy the full URL to the clipboard".
    >
    > **DO include specific, high-impact changes, for example:**
    > - Migrated core site infrastructure to the
    >   [Jaspr framework](https://jaspr.site)
    >   for an improved contributor experience.
    > - Enhanced the Glossary by adding support for
    >   [filtering by label](https://github.com/dart-lang/site-www/pull/6945)
    >   and [tooltips](https://github.com/dart-lang/site-www/pull/6969).
    > - Redesigned the
    >   [Community page](https://github.com/dart-lang/site-www/pull/6900)
    >   with a modern card-based layout.
    > - Started compiling the website's client-side Dart code to
    >   [WebAssembly](https://github.com/dart-lang/site-www/pull/6953).
    >
    > _For more examples, reference the pre-existing release sections._

4.  **Create a new release section**

    In `src/content/resources/whats-new.md`,
    create a new section at the top of the file
    (just below the header/introduction) for the new release.
    Follow the same formatting and structure of
    past releases on the page:

    -   A heading with the release version,
        like `## 3.12 release` for Dart 3.12.
    -   A release date line,
        like `_Released on: <Date>_`.
        Ask the developer for the release date,
        or if it's not available yet, leave a placeholder.
    -   A short summary paragraph describing what the section covers,
        including the date range between the previous release and this one.
    -   Subsections for different types of changes,
        such as "documentation updates", "site improvements", etc.

    **Update the global metadata:**
    Update the `lastVerified` field in the page's YAML frontmatter
    to the new release date or if not available, today's date.

5.  **Add entries for meaningful changes**

    For each meaningful change identified in Step 3:

    -   Add an entry under the appropriate subsection,
        for example, under the "documentation updates" section.
    -   Write a concise explanation of the change.
    -   Add a link to the relevant section or new page.
        Include the link as a cross-link from the text,
        not as a standalone, full URL.
    -   If a third-party contributor was involved
        (indicated by the commit's or PR's author information),
        thank them by including their GitHub handle in parentheses,
        for example: `(Thank you, [username][].)`.

    **Note:** Only include third-party contributors;
    don't include Dart and Flutter team members, such as Daco or Parker.

6.  **Format glossary terms for hover tooltips**

    If any new glossary terms were added,
    link to their specific fragment anchor on the glossary page.
    This enables a hover tooltip for the reader.
    For example, structure the links at the bottom
    of the release section like this:

    ```markdown
    [top type]: /resources/glossary#top-type
    [null safety]: /resources/glossary#null-safety
    [sound]: /resources/glossary#sound
    ```

7.  **Add the release announcement link or a placeholder**

    Include links for the release announcement and
    the SDK changelog entries for that version.
    Ask the developer for the announcement blog link,
    or if it's not available yet, use a placeholder.
    Also include a link to the release's corresponding
    changelog entries as done in past releases.

8.  **Add and format link definitions**

    Add the link definitions of Markdown reference links
    to the bottom of the new release section,
    matching the style used throughout the document.
    For example: `[3.11 announcement]: https://...`.

9.  **Request review**

    Notify the developer that the `whats-new.md` page has been updated and
    ask them to verify the changes.