Skip to content

Team guide

Jump to bottom
Amanda Fitch edited this page Mar 13, 2025 · 7 revisions

This is a guide for the Dart team members who are responsible for maintaining dart-lang/site-www.

Dart SDK release process

Make these updates

Don't make these updates

  • The SDK version used by repo tools. This is controlled by the topmost pubspec.yaml. Unless you're updating the tools, there's no need to update this.

Test a proposed SDK release

  1. Verify you have updated the checksums as outlined in the Dart SDK and Node PPA Checksum values instructions.

  2. From the root directory, run the build with tests:

    $ make test

Update Wikipedia

Here's how to update the stable release info in the Dart Wikipedia page:

  1. In the box at the right of the page, click the pencil next to the Stable release number.
  2. Scroll to the bottom of the software version identifier section, and click + add value.
    If it tells you to log into Wikidata, you can do that at the top of the page.
  3. In the text field that comes up, enter the release number.
    Example: 2.16.0
  4. Click + add qualifier, choose publication date, and add the date.
    Example: 3 February 2022
  5. Click + add reference, choose reference URL, and set it to the URL of to the tagged release.
    Example: https://github.com/dart-lang/sdk/releases/tag/2.16.0
  6. Now make the new release be displayed:
    1. To the left of the release number is an icon like a tiny scrollbar. Click the top triangle to select it.
    2. In the icon to the left of the previous release number, click the circle to select it.

Note: Some releases (2.13.3, for example), have more fields in the reference, such as retrieved, title, & publication date. I don’t know whether these matter.

History of version updates: https://www.wikidata.org/w/index.php?title=Q406009&action=history

Release process notes (WIP)

This guide describes the Dart release process for technical writers. A minor release happens approximately every 3-4 months. This process needs to start at the beginning of the "release cycle" (release date to release date), and spans the entire cycle.

In summary, the release process involves:

  • setting up the repo for incoming release work,
  • gathering developments going into the release,
  • tracking the developments relevant to documentation,
  • studying development artifacts to...
    • evaluate their relevance to documentation, and
    • determine what documentation work they necessitate,
  • executing that documentation work,
  • preparing the site updates for when the version releases.

Prerequisites

Branch strategy (prepare)

Current strategy, under evaluation

Release docs work can not go live on dart.dev until the actual release day. For this reason, we create a target version branch in the repo to point all release PRs to over the course of the release cycle. This way, we can close PRs as they finish so they don't crowd the repo's open PRs table. The version branch gets merged into main on release day.

  1. Once the first beta for the upcoming release is made...

    • Create the new branch:
      • Branch from main
      • Version branch name should be vX.X (e.g. v2.19)

  2. To enable testing and staging for the upcoming release...

    • Update the action files and Dockerfile to accommodate the dev branch.

  3. Open a draft [Tracking] PR with the changes from step 2 targeting main

    • This is where commit history of the doc PRs targeting the version branch can be interactively rebased (right before the merge into main)
    • This step is in trial, and a precaution in case it becomes necessary. It might be possible to just squash the commit history before merging into main at the end.

  4. (Optional / Recommended) Have a separate local repo for all the Dart 3 work that will be targeting the version branch

    • Otherwise, switching between the version branch and main will require a make setup every time.

Gather release developments

Dart is made up of multiple teams, and a release is the culmination of work from all of them. Dart teams track and document their work differently, so it's important to know where to look for release developments.

(TODO): ("Dart teams" summary page, write about what the teams do, how to navigate their work, etc)

  1. The change log

    The change log is the most complete resource for tracking developments going into a release. The only issues with using it as a resource are:

Track release developments

As you gather release developments, it's important to keep track of what you find so you can return to them later on for closer evaluation. Keeping track also makes it easier to verify coverage with PMs.

The best way to do this is to create a GitHub Project. It gives you a single source to share and reference. This is very valuable for verifying coverage with PMs. You can all look at the project and say "This is what I've found for developments; is anything missing?; are any of these completely irrelevant to documentation?" * It's also beneficial because it allows engineers to add their own work to the project (TODO: have to actually inform engineers that they can do this and let them know how)

*Be careful with this question. The only things that are truly irrelevant are performance enhancements, tests, and maybe diagnostics because that team handles their own documentation.

GitHub Project for release docs

TBD

Investigate and evaluate release developments

TBD

Branch strategy (end of cycle)

TBD

Write and PRs

Technical aspects of writing and PRs: branch, update w/main, submodules, use vs code, etc. code excerpts, changing you dart channel to dev

Final updates

Blog

What's new

Language Evolution

Wikipedia

Banner

Language feature specification and proposal link updates

Clone this wiki locally