How to release the next version of DevTools

Configure/Refresh environment

Make sure:

1. Your Dart SDK is configured:

   a. You have a local checkout of the Dart SDK

   • (for getting started instructions, see sdk/CONTRIBUTING.md).

   b. Ensure your .bashrc sets $LOCAL_DART_SDK

   ```shell
   DART_SDK_REPO_DIR=<Path to cloned dart sdk>
   export LOCAL_DART_SDK=$DART_SDK_REPO_DIR/sdk
   ```
   

   c. The local checkout is at main branch: git rebase-update

2. Your Flutter version is equal to latest candidate release branch:

   • Run ./tool/update_flutter_sdk.sh --local from the main devtools directory.

3. You have goma configured.

Prepare the release

Update the DevTools version number

• Make sure your working branch is clean
• Run the tool/release_helper.sh script with minor or major. ./tool/release_helper.sh [minor|major]
• This creates 2 branches for you:
  • Release Branch
  • Next Branch
• The following steps will guide you through how these branches will be prepared and merged.
• For your convenience, the tool/release_helper.sh script exports the following two variables to the terminal it is run in:
  • $DEVTOOLS_RELEASE_BRANCH
  • $DEVTOOLS_NEXT_BRANCH

Verify the version changes for $DEVTOOLS_RELEASE_BRANCH

Verify release_helper.sh script:

• updated the pubspecs under packages/
• updated all references to those packages
• updated the version constant in packages/devtools_app/lib/devtools.dart

These packages always have their version numbers updated in lock, so we don't have to worry about versioning.

Manually review the CHANGELOG.md in $DEVTOOLS_RELEASE_BRANCH

Review/update CHANGELOG.md:

1. Verify all changes are here:

   • Open commits
   • Search for last PR, commented for previous version in CHANGELOG
   • Make sure all PRs since the found one are included. You may want to re-run dart tool/bin/repo_tool.dart generate-changelog --since-tag=<tag like v1.5.2> with passed parameter for the tag.

2. Verify the version for the CHANGELOG entry was correctly generated.

3. Verify each item is a complete sentence, written as though it was an order, and there is no syntax errors.

4. Create draft PR for the branch and add the item for it to the top.

Test the $DEVTOOLS_RELEASE_BRANCH

• Checkout the $DEVTOOLS_RELEASE_BRANCH,

• Build the DevTools binary and run it from your local Dart SDK.

  • From the main devtools/ directory.

  dart ./tool/build_e2e.dart
  

• Launch DevTools and verify that everything generally works.

  • open the page in a browser (http://localhost:53432)
  • flutter run an application
  • connect to the running app from DevTools
  • verify:
    • pages generally work
    • there are no exceptions in the chrome devtools log
  • If you find any release blocking issues:
    • fix them before releasing.
    • Then grab the latest commit hash that includes
      • the release prep commit
      • the bug fixes,
    • use this commit hash for the following steps.

• Once the build is in good shape,

  • revert any local changes.

    git checkout . && \
    git clean -f -d;
    

Push the $DEVTOOLS_RELEASE_BRANCH

Ensure you are still on the $DEVTOOLS_RELEASE_BRANCH

git push -u origin $DEVTOOLS_RELEASE_BRANCH

From the git GUI tool or from github.com directly:

1. Create a PR.
2. Add the entry about the created PR to the CHANGELOG.md manually, and push to the PR.
3. Receive an LGTM, squash and commit.

Tag the release

• Checkout the commit from which you want to release DevTools

  • This is likely the commit for the PR you just landed
  • You can run git log -v to see the commits.

• Run the tag_version.sh script

  • this creates a tag on the flutter/devtools repo for this release.
  • This script will automatically determine the version from packages/devtools/pubspec.yaml so there is no need to manually enter the version.

  tool/tag_version.sh;
  

Verify and Submit the release notes

See the release notes README.md for details on where to add DevTools release notes to Flutter website and how to test them.

• Follow the release notes README.md to add release notes to Flutter website
  • On the $DEVTOOLS_RELEASE_BRANCH copy the release notes from NEXT_RELEASE_NOTES.md
    • These are the release notes you will submit through the flutter/website PR.
  • make sure to also follow the instructions to test them.

Upload the DevTools binary to CIPD

• Use the update.sh script to build and upload the DevTools binary to CIPD:

  TARGET_COMMIT_HASH=<Commit hash for the version bump commit in DevTools>
  

  cd $LOCAL_DART_SDK && \
  git rebase-update && \
  third_party/devtools/update.sh $TARGET_COMMIT_HASH [optional --no-update-flutter];
  

For cherry pick releases that need to be built from a specific version of Flutter, checkout the Flutter version on your local flutter repo (the Flutter SDK that which flutter points to). Then when you run the update.sh command, include the --no-update-flutter flag:

third_party/devtools/update.sh $TARGET_COMMIT_HASH --no-update-flutter

Update the DevTools hash in the Dart SDK

• Create new branch for your changes:

  cd $LOCAL_DART_SDK && \
  git new-branch dt-release;
  

• Update the devtools_rev entry in the Dart SDK DEPS file

  • set the devtools_rev entry to the TARGET_COMMIT_HASH.
  • See this example CL for reference.

• Build the dart sdk locally

  cd $LOCAL_DART_SDK && \
  gclient sync -D && \
  ./tools/build.py -mrelease -ax64 create_sdk;
  

• Verify that running dart devtools launches the version of DevTools you just released.

  • for OSX

    xcodebuild/ReleaseX64/dart-sdk/bin/dart devtools
    

  • For non-OSX

    out/ReleaseX64/dart-sdk/bin/dart devtools
    

• If the version of DevTools you just published to CIPD loads properly

  You may need to hard reload and clear your browser cache in order to see the changes.

  • push up the SDK CL for review.

    git add . && \
    git commit -m "Bump DevTools DEP to $NEW_DEVTOOLS_VERSION" && \
    git cl upload -s;
    

Publish package:devtools_shared on pub

package:devtools_shared is the only DevTools package that is published on pub.

• From the devtools/packages/devtools_shared directory, run:

  flutter pub publish
  

Push the DEVTOOLS_NEXT_BRANCH

git pull upstream master
git checkout $DEVTOOLS_NEXT_BRANCH
git push -u origin $DEVTOOLS_NEXT_BRANCH

From the git GUI tool or from github.com directly:

1. Create a PR.
2. Receive an LGTM, squash and commit.