Skip to content

Dartdoc release engineering

Jump to bottom
jcollins-g edited this page Jun 22, 2018 · 4 revisions

Dartdoc Release Engineering

Overview

The basic steps for releasing a new Dartdoc package are:

  1. Run pub run grinder publish at the desired commit to validate that the package has no warnings or errors and that basic sanity checks pass.
  2. 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 increment the dartdoc version.
  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

  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-docs-flutter-io.firebaseapp.com/.
Clone this wiki locally