Changelog System for Dart Docs #7056

antfitch · 2025-12-04T21:40:10Z

Description:

This PR refactors the changelog implementation to use a hybrid static/dynamic architecture and migrates the Dart SDK Chagelog, Breaking Changes page, Language Evolution page to this new system.

Preview:

https://dart-dev--pr7056-breaking-changes-migration-9su53cep.web.app/changelog

Stages for this PR before we merge:

This PR has a few stages. This is the workflow I plan to follow:

First batch of commits: code quality review, make sure nothing is missing that was in Breaking Changes, Language Evolution, Dart SDK Changelog.
Second batch of commits: @antfitch to remove Breaking Changes, Language Evolution, and Dart SDK Changelog from the TOC (please note that we will not be removing the CHANGELOG.md from it's repo, but we will no longer directly link to it in our TOC)

Key Changes:

Architecture: Implemented a new hybrid architecture where changelog content is rendered statically (SSG) for SEO and performance, while client-side filtering is handled via a lightweight JavaScript layer.
Components:
- Created ChangelogIndex as the main server component.
- Implemented ChangelogFilters and ChangelogFiltersSidebar for client-side interactivity.
- Added shared filtering components (CheckboxFilterGroup, FilterToolbar).
Data Model: Introduced ChangelogEntry model that parses data from YAML on the server and re-hydrates from DOM data- attributes on the client.
Documentation: Added site/doc/changelog_architecture.md detailing the new architecture, data flow, and maintenance guide.
Content: Migrated content to src/data/changelog.yml.

What's after this PR:

After this PR is merged, I will move the Dart doc site changes into the new Changelog system.

gemini-code-assist · 2025-12-04T21:40:34Z

Summary of Changes

Hello @antfitch, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the changelog system for Dart documentation, moving from disparate pages to a unified, interactive experience. The new system leverages a hybrid static and client-side approach to ensure optimal performance and search engine visibility while providing users with dynamic filtering and search capabilities. This change centralizes content management and introduces a robust, well-documented architecture for future maintainability.

Highlights

New Changelog Architecture: Implemented a hybrid static/dynamic architecture for the changelog page, combining static-site generation (SSG) for SEO and initial load performance with client-side JavaScript for interactive filtering and searching.
Content Migration: Migrated existing changelog content, including the Dart SDK Changelog, Breaking Changes page, and Language Evolution page, to this new centralized system, with content now stored in src/data/changelog.yml.
New Components and Data Model: Introduced several new components: ChangelogIndex (main server component), ChangelogFilters and ChangelogFiltersSidebar (client-side interactivity), and shared filtering UI components. A new ChangelogEntry data model was created to parse YAML data server-side and re-hydrate from DOM data- attributes client-side.
Comprehensive Documentation: Added a detailed site/doc/changelog_architecture.md document, outlining the new architecture, data flow, and a maintenance guide for managing changelog entries.
Improved Markdown Parsing: Enhanced the DashMarkdown component to support inline parsing and more robustly handle text content within nodes, improving markdown rendering capabilities.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new changelog system for Dart documentation, featuring a hybrid static/dynamic architecture for improved SEO and user experience. The changes include new Dart components for filtering and displaying changelog entries, along with corresponding SCSS for styling and a detailed architecture document. The implementation appears well-structured, leveraging client-side interactivity for filtering while maintaining static rendering for initial load performance. The new system also includes a clear data model and management guide for changelog entries. Overall, the changes are comprehensive and well-executed, enhancing the usability and maintainability of the changelog page.

dart-github-bot · 2025-12-04T21:47:13Z

Visit the preview URL for this PR (updated for commit 21b0257):

https://dart-dev--pr7056-breaking-changes-migration-9su53cep.web.app

site/lib/_sass/base/_utils.scss

antfitch · 2025-12-05T01:13:46Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a well-architected changelog system using a hybrid static/dynamic approach, which is a great improvement for both SEO and user experience. The new architecture is thoroughly documented, and the migration of existing content into the new YAML-based system is a significant step forward. My review focuses on improving the maintainability of the new CSS, ensuring the correctness of the generated HTML, and refining some of the Dart implementation details. Overall, this is a solid contribution.

site/lib/src/components/pages/changelog/changelog_index.dart

site/lib/_sass/base/_utils.scss

site/lib/_sass/pages/_changelog-index.scss

site/lib/src/components/pages/changelog/changelog_filters_sidebar.dart

site/lib/src/components/pages/changelog/changelog_index.dart

… Dart code improvements

antfitch · 2025-12-05T23:03:55Z

This is ready for review. @parlough, @ericwindmill, and @kevmoo if you need any changes, let me know.

kevmoo · 2025-12-06T22:30:57Z

I didn't review the code, but I noticed the staged version:

See the double title thingy?

ericwindmill

I left a few comments, all of which are small and/or just style opinions.

I am not a web expert or Jaspr expert, so @parlough's opinion would be valuable here.

ericwindmill · 2025-12-08T17:19:12Z

site/lib/main.dart

+  //   pattern: RegExp('LearningResourceIndex', caseSensitive: false),
+  //   builder: (_, _, _) => LearningResourceIndex(),
+  // ),


We shouldn't leave commented out code in the codebase

ericwindmill · 2025-12-08T17:21:13Z

site/lib/src/models/changelog_model.dart

+  deprecated('deprecated', 'Deprecated'),
+  removed('removed', 'Removed'),
+  none('none', 'None')
+  ;


nit: This semicolon on it's own line is weird? Maybe run dart fmt

ericwindmill · 2025-12-08T17:33:52Z

site/lib/_sass/pages/_changelog-index.scss

+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.2);
+  width: 90%;
+  max-width: 600px;
+  max-height: 90vh;


I think the max-width should have a larger max width, it looks cramped when the desktop window is full screen.

ericwindmill · 2025-12-08T17:36:58Z

site/lib/_sass/pages/_changelog-index.scss

+
+    dl {
+      display: grid;
+      grid-template-columns: max-content 1fr;


Similar to my above comment, I think this should be something like 2fr 3fr. The content looks cramped because the first column takes up most of the space, but has less content. Alternatively, you could explicitly make the content in column 1 be on two lines, so the max-content width isn't so long.

ericwindmill · 2025-12-08T17:41:10Z

site/lib/_sass/pages/_changelog-index.scss

+    }
+
+    dl {
+      display: grid;


The legend popup is pretty is hard to read on mobile. Consider using grid-template-area to make the grid shape change based on the width of the screen. For example, the "type of change" could be listed above the paragraph of explainer text on mobile, and in columns (as it is now) on larger screens

antfitch · 2025-12-08T20:12:08Z

Let's choose a data serialization strategy for Dash sites before committing this.

Refactor changelog components and migrate breaking changes page

8e51f50

antfitch requested review from ericwindmill and parlough December 4, 2025 21:40

Merge branch 'main' into breaking-changes-migration

ccadcc3

antfitch self-assigned this Dec 4, 2025

antfitch added the infra.design Relates to the design of docs.Dart.dev label Dec 4, 2025

gemini-code-assist bot reviewed Dec 4, 2025

View reviewed changes

Ran dart format .

083b552

antfitch added 3 commits December 4, 2025 16:42

Fix broken link reference in changelog

554d396

Fix broken links in changelog and update style hash

6a31235

Reflow changelog.yml to 80 chars

50689bd

kevmoo reviewed Dec 5, 2025

View reviewed changes

site/lib/_sass/base/_utils.scss Outdated Show resolved Hide resolved

gemini-code-assist bot reviewed Dec 5, 2025

View reviewed changes

Address PR review comments: fix SCSS variables, dark mode colors, and…

21b0257

… Dart code improvements

antfitch marked this pull request as ready for review December 5, 2025 23:03

ericwindmill requested changes Dec 8, 2025

View reviewed changes

Changelog System for Dart Docs #7056

Are you sure you want to change the base?

Changelog System for Dart Docs #7056

Uh oh!

Conversation

antfitch commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Dec 4, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

dart-github-bot commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

antfitch commented Dec 5, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

antfitch commented Dec 5, 2025

Uh oh!

kevmoo commented Dec 6, 2025

Uh oh!

ericwindmill left a comment

Choose a reason for hiding this comment

Uh oh!

ericwindmill Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

ericwindmill Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

ericwindmill Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

ericwindmill Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

ericwindmill Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

antfitch commented Dec 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

antfitch commented Dec 4, 2025 •

edited

Loading

dart-github-bot commented Dec 4, 2025 •

edited

Loading