Release notes updates for flutter/website expectations (#9605)
diff --git a/packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md b/packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md index dec446f..79a9508 100644 --- a/packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md +++ b/packages/devtools_app/release_notes/NEXT_RELEASE_NOTES.md
@@ -3,7 +3,7 @@ Use of this source code is governed by a BSD-style license that can be found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd. --> -This is draft for future release notes, that are going to land on +This is a draft for future release notes that are going to land on [the Flutter website](https://docs.flutter.dev/tools/devtools/release-notes). # DevTools 2.55.0 release notes @@ -11,7 +11,7 @@ The 2.55.0 release of the Dart and Flutter DevTools includes the following changes among other general improvements. To learn more about DevTools, check out the -[DevTools overview](/tools/devtools/overview). +[DevTools overview](/tools/devtools). ## General updates @@ -53,11 +53,11 @@ TODO: Remove this section if there are not any updates. -## VS Code Sidebar updates +## VS Code sidebar updates TODO: Remove this section if there are not any updates. -## DevTools Extension updates +## DevTools extension updates TODO: Remove this section if there are not any updates.
diff --git a/packages/devtools_app/release_notes/README.md b/packages/devtools_app/release_notes/README.md index 62b8245..0a697bf 100644 --- a/packages/devtools_app/release_notes/README.md +++ b/packages/devtools_app/release_notes/README.md
@@ -8,7 +8,8 @@ When you add a user-facing change to DevTools, please add a release note entry to document this improvement. -This entry should be phrased in the past tense (e.g. "Added XYZ" instead of "Add XYZ"). +This entry should be phrased in the past tense. +For example, "Added XYZ" instead of "Add XYZ". ### Release note entry @@ -16,12 +17,12 @@ ```markdown * Created the best feature ever. - -[#10000000001](https://github.com/flutter/devtools/pull/10000000001), -[#10000000002](https://github.com/flutter/devtools/pull/10000000002), -[#10000000003](https://github.com/flutter/devtools/pull/10000000003) + [#10000000001](https://github.com/flutter/devtools/pull/10000000001), + [#10000000002](https://github.com/flutter/devtools/pull/10000000002), + [#10000000003](https://github.com/flutter/devtools/pull/10000000003) ``` -Find other examples in [previous notes](https://github.com/flutter/website/tree/main/src/tools/devtools/release-notes). +Find other examples in [previous notes](https://github.com/flutter/website/tree/main/src/content/tools/devtools/release-notes). ### Adding images to a release note entry @@ -37,10 +38,12 @@ ``` #### Image style -Please use DevTools in **dark mode** when taking screenshots for release -notes. We use a dark theme since this is the default theme for DevTools. + +Please use DevTools in **dark mode** when taking screenshots for release notes. +We use a dark theme since this is the default theme for DevTools. #### Image size + When adding images, be cognizant that the images will be rendered in a relatively small window in DevTools, and they should be sized accordingly. A wide aspect ratio is preferred so that the space of the release notes @@ -58,7 +61,9 @@ ### Creating the release notes PR -Draft release notes on a local `flutter/website` branch using the following command: +Draft release notes on a local `flutter/website` branch by running +the following command with the path to your local `flutter/website` repo: + ```console dt release-notes -w /Users/me/absolute/path/to/flutter/website ```
diff --git a/packages/devtools_app/release_notes/helpers/release_notes_template.md b/packages/devtools_app/release_notes/helpers/release_notes_template.md index 63b3034..f108e00 100644 --- a/packages/devtools_app/release_notes/helpers/release_notes_template.md +++ b/packages/devtools_app/release_notes/helpers/release_notes_template.md
@@ -3,7 +3,7 @@ Use of this source code is governed by a BSD-style license that can be found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd. --> -This is draft for future release notes, that are going to land on +This is a draft for future release notes that are going to land on [the Flutter website](https://docs.flutter.dev/tools/devtools/release-notes). # DevTools <number> release notes @@ -11,7 +11,7 @@ The <number> release of the Dart and Flutter DevTools includes the following changes among other general improvements. To learn more about DevTools, check out the -[DevTools overview](/tools/devtools/overview). +[DevTools overview](/tools/devtools). ## General updates @@ -53,11 +53,11 @@ TODO: Remove this section if there are not any updates. -## VS Code Sidebar updates +## VS Code sidebar updates TODO: Remove this section if there are not any updates. -## DevTools Extension updates +## DevTools extension updates TODO: Remove this section if there are not any updates.
diff --git a/tool/lib/commands/release_notes_helper.dart b/tool/lib/commands/release_notes_helper.dart index 5c72087..f70abc0 100644 --- a/tool/lib/commands/release_notes_helper.dart +++ b/tool/lib/commands/release_notes_helper.dart
@@ -68,7 +68,6 @@ CliCommand.git(['stash']), CliCommand.git(['checkout', 'main']), CliCommand.git(['pull']), - CliCommand.git(['submodule', 'update', '--init', '--recursive']), CliCommand.git([ 'checkout', '-b', @@ -114,7 +113,7 @@ ), )..createSync(); - final srcLines = devToolsReleaseNotes.srcLines; + final srcLines = devToolsReleaseNotes.sourceLines; // Copy release notes images and fix image reference paths. if (devToolsReleaseNotes.imageLineIndices.isNotEmpty) { @@ -142,19 +141,19 @@ } } - final metadataHeader = '''--- + releaseNotesMd.writeAsStringSync('''--- title: DevTools $releaseNotesVersion release notes shortTitle: $releaseNotesVersion release notes breadcrumb: $releaseNotesVersion showToc: false --- -'''; +'''); - // Write the 'release-notes-<x.y.z>.md' file, including any updates for - // image paths. + // Write the contents of the 'release-notes-<x.y.z>.md' file, + // including any updates for image paths. releaseNotesMd.writeAsStringSync( - metadataHeader + srcLines.joinWithNewLine(), + srcLines.joinWithNewLine().trimLeft(), flush: true, ); @@ -178,7 +177,7 @@ _DevToolsReleaseNotes._({ required this.file, required this.version, - required this.srcLines, + required this.sourceLines, required this.imageLineIndices, }); @@ -192,8 +191,8 @@ final rawLines = file.readAsLinesSync(); - late String version; - late int titleLineIndex; + String? version; + int? sourceStartIndex; final versionRegExp = RegExp(r"\d+\.\d+\.\d+"); for (int i = 0; i < rawLines.length; i++) { final line = rawLines[i]; @@ -202,17 +201,34 @@ // This match should be from the line "# DevTools <x.y.z> release notes". version = matches.first.group(0)!; // This is the markdown title where the release notes src begins. - titleLineIndex = i; + sourceStartIndex = i + 1; break; } + if (version == null || sourceStartIndex == null) { + throw Exception( + 'Could not find the title line ("# DevTools x.y.z release notes") ' + 'in the NEXT_RELEASE_NOTES.md file.', + ); + } + + if (sourceStartIndex >= rawLines.length) { + throw Exception( + 'No content found after the title line ("# DevTools x.y.z release notes") ' + 'in the NEXT_RELEASE_NOTES.md file.', + ); + } + + // Don't include the copyright, draft notice, or h1 header in + // the output release notes. + final sourceLines = rawLines.sublist(sourceStartIndex); + // TODO(kenz): one nice polish task could be to remove sections that are // empty (i.e. sections that have the line // "TODO: Remove this section if there are not any updates."). - final srcLines = rawLines.sublist(titleLineIndex); final imageLineIndices = <int>{}; - for (int i = 0; i < srcLines.length; i++) { - final line = srcLines[i]; + for (int i = 0; i < sourceLines.length; i++) { + final line = sourceLines[i]; if (line.contains(_imagePathMarker)) { imageLineIndices.add(i); } @@ -221,14 +237,14 @@ return _DevToolsReleaseNotes._( file: file, version: version, - srcLines: srcLines, + sourceLines: sourceLines, imageLineIndices: imageLineIndices, ); } final File file; final String version; - final List<String> srcLines; + final List<String> sourceLines; final Set<int> imageLineIndices; static final _imagePathMarker = RegExp(r'images\/.*\.png');