(WIP) Release documentation process for technical writers

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

• Set up local repo to work in : Dart - Getting Started

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.
     • See this commit for files and lines to update

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

Investigate and evaluate release developments

Branch strategy (end of cycle)

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