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 for an improved contributor experience.
   • Enhanced the Glossary by adding support for filtering by label and tooltips.
   • Redesigned the Community page with a modern card-based layout.
   • Started compiling the website's client-side Dart code to WebAssembly.

   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:

   [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.