From 7268a6588be0ea53dbba3896ffd4704d4f7c0b8c Mon Sep 17 00:00:00 2001 From: Kenzie Davisson <43759233+kenzieschmoll@users.noreply.github.com> Date: Tue, 8 Mar 2022 10:16:03 -0800 Subject: [PATCH] Add instructions and functionality for testing new release notes (#3803) --- packages/devtools_app/lib/src/app.dart | 2 +- .../lib/src/shared/release_notes/README.md | 48 +++++++++++++++++++ .../{ => release_notes}/release_notes.dart | 29 ++++++----- tool/README.md | 25 ++++++---- 4 files changed, 82 insertions(+), 22 deletions(-) create mode 100644 packages/devtools_app/lib/src/shared/release_notes/README.md rename packages/devtools_app/lib/src/shared/{ => release_notes}/release_notes.dart (90%) diff --git a/packages/devtools_app/lib/src/app.dart b/packages/devtools_app/lib/src/app.dart index 34269b0ba73..1a6f16b5e45 100644 --- a/packages/devtools_app/lib/src/app.dart +++ b/packages/devtools_app/lib/src/app.dart @@ -44,7 +44,7 @@ import 'shared/globals.dart'; import 'shared/initializer.dart'; import 'shared/landing_screen.dart'; import 'shared/notifications.dart'; -import 'shared/release_notes.dart'; +import 'shared/release_notes/release_notes.dart'; import 'shared/routing.dart'; import 'shared/scaffold.dart'; import 'shared/screen.dart'; diff --git a/packages/devtools_app/lib/src/shared/release_notes/README.md b/packages/devtools_app/lib/src/shared/release_notes/README.md new file mode 100644 index 00000000000..ea38bd113fa --- /dev/null +++ b/packages/devtools_app/lib/src/shared/release_notes/README.md @@ -0,0 +1,48 @@ +## Writing DevTools release notes +Release notes for DevTools are hosted on the flutter website (see [archive](https://docs.flutter.dev/development/tools/devtools/release-notes)). +To add release notes for the latest release, create a PR with the appropriate changes for your release (see example +[PR](https://github.com/flutter/website/pull/6791)). + +Test these changes locally before creating the PR. See [README.md](https://github.com/flutter/website/blob/main/README.md) +for getting setup to run the Flutter website locally. + +One you are satisfied with the release notes, stage the Flutter website on Firebase and point the DevTools release notes +logic to this staged url. + +### Staging your changes on Firebase +In the flutter/website directory, open [_config.yml](https://github.com/flutter/website/blob/main/_config.yml#L2) +and replace `https://docs.flutter.dev` with `https://flutter-website-dt-staging.web.app` (line 2). + +Then run the following rom the `website/` directory: +```dart +make setup; +DISABLE_TESTS=1 make build; +firebase deploy --project devtools-staging --only hosting +``` + +Once you see this message, the deployment was successful and now you can move on to the next step. +```shell +... + +✔ Deploy complete! + +Project Console: https://console.firebase.google.com/project/flutter-website-dt-staging/overview +Hosting URL: https://flutter-website-dt-staging.web.app +``` + +### Testing the release notes in DevTools +In `release_notes.dart` flip the `debugTestReleaseNotes` flag to true. + +Then, from the main `devtools/` directory, run the following: +```dart +dart ./tool/build_e2e.dart +``` + +Once DevTools has been successfully built and served, you should see the following the CLI output: +```shell +... + +Serving DevTools with a local devtools server... +Serving DevTools at http://127.0.0.1:57336. +``` +Visit the DevTools link, and verify that the release notes viewer displays the new release notes as expected. \ No newline at end of file diff --git a/packages/devtools_app/lib/src/shared/release_notes.dart b/packages/devtools_app/lib/src/shared/release_notes/release_notes.dart similarity index 90% rename from packages/devtools_app/lib/src/shared/release_notes.dart rename to packages/devtools_app/lib/src/shared/release_notes/release_notes.dart index deff1d7bf24..42aa164b3e9 100644 --- a/packages/devtools_app/lib/src/shared/release_notes.dart +++ b/packages/devtools_app/lib/src/shared/release_notes/release_notes.dart @@ -11,15 +11,17 @@ import 'package:flutter/material.dart'; import 'package:flutter_markdown/flutter_markdown.dart'; import 'package:http/http.dart' as http; -import '../../devtools.dart' as devtools; -import '../config_specific/launch_url/launch_url.dart'; -import '../config_specific/logger/logger.dart' as logger; -import '../config_specific/server/server.dart' as server; -import '../primitives/auto_dispose_mixin.dart'; -import 'common_widgets.dart'; -import 'theme.dart'; -import 'utils.dart'; -import 'version.dart'; +import '../../../devtools.dart' as devtools; +import '../../config_specific/launch_url/launch_url.dart'; +import '../../config_specific/logger/logger.dart' as logger; +import '../../config_specific/server/server.dart' as server; +import '../../primitives/auto_dispose_mixin.dart'; +import '../common_widgets.dart'; +import '../theme.dart'; +import '../utils.dart'; +import '../version.dart'; + +const debugTestReleaseNotes = false; class ReleaseNotesViewer extends StatefulWidget { const ReleaseNotesViewer({ @@ -169,7 +171,9 @@ class ReleaseNotesController { static const _unsupportedPathSyntax = '{{site.url}}'; - static const _flutterDocsSite = 'https://docs.flutter.dev'; + String get _flutterDocsSite => debugTestReleaseNotes + ? 'https://flutter-website-dt-staging.web.app' + : 'https://docs.flutter.dev'; ValueListenable get releaseNotesMarkdown => _releaseNotesMarkdown; @@ -189,7 +193,7 @@ class ReleaseNotesController { final lastReleaseNotesShownVersion = await server.getLastShownReleaseNotesVersion(); SemanticVersion previousVersion; - if (lastReleaseNotesShownVersion.isEmpty) { + if (debugTestReleaseNotes || lastReleaseNotesShownVersion.isEmpty) { previousVersion = SemanticVersion(); } else { previousVersion = SemanticVersion.parse(lastReleaseNotesShownVersion); @@ -238,6 +242,7 @@ class ReleaseNotesController { } String _releaseNotesUrl(String currentVersion) { - return 'https://docs.flutter.dev/development/tools/devtools/release-notes/release-notes-$currentVersion-src.md'; + return '$_flutterDocsSite/development/tools/devtools/release-notes/' + 'release-notes-$currentVersion-src.md'; } } diff --git a/tool/README.md b/tool/README.md index 302dd1f294f..57edd1da7b6 100644 --- a/tool/README.md +++ b/tool/README.md @@ -95,14 +95,6 @@ git rebase-update third_party/devtools/update.sh 8881a7caa9067471008a8e00750b161f53cdb843 ``` -### 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: -```shell -pub publish -``` - ### Update the DevTools hash in the Dart SDK Update the `devtools_rev` entry in the Dart SDK @@ -118,4 +110,19 @@ cd path/to/dart-sdk/sdk gclient sync -D ./tools/build.py -mrelease -ax64 create_sdk out/ReleaseX64/dart-sdk/bin/dart devtools # On OSX replace 'out' with 'xcodebuild' -``` \ No newline at end of file +``` + +### 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: +```shell +pub publish +``` + +### Write release notes for the release +Release notes should contain details about the user-facing changes included in the release. +These notes are shown directly in DevTools when a user opens a new version of DevTools. Please +see the release notes +[README.md](https://github.com/flutter/devtools/blob/master/packages/devtools_app/lib/src/shared/release_notes/README.md) +for details on where to add release notes and how to test them.