Skip to content

Dartdoc release engineering

Jump to bottom
Janice Collins edited this page Jun 30, 2021 · 4 revisions

Dartdoc Release Engineering

Overview

The basic steps for releasing a new Dartdoc package are:

  1. Update the pubspec.yaml and CHANGELOG.md for the new version, and run grind build to regenerate files depending on the version of dartdoc.
  2. Run pub run grinder presubmit at the desired commit to validate that the package has no warnings or errors and that basic sanity checks pass.
  3. Run DARTDOC_ORIGINAL=[previous version tag] pub run grinder compare-flutter-warnings to validate that the new dartdoc version doesn't radically alter dartdoc's behavior for flutter in unexpected ways. The grinder will compare warnings for you.

Temp directories generated are left around after this, so you can compare the output files directly. Pull the directory names from the output:

As an example, the new version will be at:

flutter-docs-current: Success! Docs generated into /tmp/flutterVVGNHP/dev/docs/doc/api

Old version:

flutter-docs-original: Success! Docs generated into /tmp/dartdoc-comparison-flutterDUOEUB/dev/docs/doc/api

Drop the api from both paths, and you can diff them by hand to see differences in output:

diff -urN /tmp/flutterVVGNHP/dev/docs/doc /tmp/dartdoc-comparison-flutterDUOEUB/dev/docs/doc

Consider the following grind tasks if you're trying to determine the impact of changes:

# All these tasks open local ports that you can browse generated docs with
grind serve-flutter-docs
grind serve-sdk-docs
grind serve-test-package-docs
  1. Create a release at this version: https://github.com/dart-lang/dartdoc/releases, select "Draft a new release". Create a new tag and pick the commit you tried at step 1.
  2. Run pub publish and confirm that you want to upload the package.

However, that does not cover updating the versions in important downstream packages like the Dart SDK and Flutter.

SDK

  1. Modify the DEPS file at the root of the SDK package to set the dartdoc revision to the commit matching the publish.
  2. Also upgrade any versions of dependent packages. Check for this with:
  git diff [previous version tag] pubspec.yaml
  git diff [previous version tag] pubspec.lock
  1. As a sanity check, build and install the resulting Dart SDK.
  2. Verify that dartdoc can generate documentation for itself and the sdk and has the right version:
  pub global deactivate dartdoc
  dartdoc --version
  cd ~/mydartdocclone
  dartdoc
  dartdoc --sdk-docs --output /tmp/sdkdocs
  1. Use git cl upload to upload the Dart SDK. Link to the release page on GitHub in the CL and once reviewed, submit that change via the submit queue.

Flutter

Be sure to follow all the best practices in the Flutter repository, listed here are only the specifics related to a dartdoc upgrade.

  1. Modify dev/bots/docs.sh to use the new version.
  2. In the pull request, link to the release page on GitHub and describe the results of the compare-flutter-warnings check, above.
  3. Land the pull request after review and tests pass. After landing, updated docs will appear at https://master-api.flutter.dev/.
Clone this wiki locally