Repository navigation
[batch release] Replace {{NEXT_VERSION}} placeholder in batch release
#13446
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| import 'dart:convert'; | ||
|
|
||
| import 'package:file/file.dart'; | ||
| import 'package:path/path.dart' as path; | ||
|
|
||
| /// Placeholder text that is replaced with the new release version in a batch | ||
| /// release package's Dart files in `lib/` when creating a batch release. | ||
| /// | ||
| /// For example, a deprecation message can use | ||
| /// `'This feature was deprecated in v{{NEXT_VERSION}}.'`. | ||
| const String nextVersionPlaceholder = '{{NEXT_VERSION}}'; | ||
|
|
||
| /// A text file containing [nextVersionPlaceholder]. | ||
| typedef VersionPlaceholderFile = ({File file, String content}); | ||
|
|
||
| /// The set of files to search for [nextVersionPlaceholder]. | ||
| enum VersionPlaceholderScope { | ||
| /// Files in which the batch release tooling replaces placeholders: Dart files | ||
| /// in `lib/`. | ||
| replaceable, | ||
|
|
||
| /// All text files in the package, other than those in build output or tool | ||
| /// state directories. Used to find placeholders that won't be replaced. | ||
| all; | ||
|
|
||
| /// Whether the file at [relativePath], relative to the package root, is in | ||
| /// this scope. | ||
| bool includes(String relativePath, path.Context pathContext) { | ||
| final List<String> components = pathContext.split(relativePath); | ||
| switch (this) { | ||
| case VersionPlaceholderScope.replaceable: | ||
| return components.first == 'lib' && pathContext.extension(relativePath) == '.dart'; | ||
| case VersionPlaceholderScope.all: | ||
| final List<String> directories = components.sublist(0, components.length - 1); | ||
| return !directories.any((String name) => name.startsWith('.') || name == 'build'); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| /// Returns the files in [files] that are in [scope] and contain | ||
| /// [nextVersionPlaceholder], along with their contents, in path order. | ||
| /// | ||
| /// [files] should be the files of the package rooted at [packageDirectory], | ||
| /// as returned by `PackageCommand.getFilesForPackage`. | ||
| Future<List<VersionPlaceholderFile>> findVersionPlaceholderFiles( | ||
| Directory packageDirectory, | ||
| Stream<File> files, { | ||
| required VersionPlaceholderScope scope, | ||
| }) async { | ||
| final path.Context pathContext = packageDirectory.fileSystem.path; | ||
| final List<File> candidates = | ||
| await files | ||
| .where( | ||
| (File file) => scope.includes( | ||
| pathContext.relative(file.path, from: packageDirectory.path), | ||
| pathContext, | ||
| ), | ||
| ) | ||
| .toList() | ||
| ..sort((File a, File b) => a.path.compareTo(b.path)); | ||
| return <VersionPlaceholderFile>[ | ||
| for (final File file in candidates) | ||
| if (_readUtf8(file) case final String content when content.contains(nextVersionPlaceholder)) | ||
| (file: file, content: content), | ||
| ]; | ||
| } | ||
|
|
||
| String? _readUtf8(File file) { | ||
| try { | ||
| return utf8.decode(file.readAsBytesSync()); | ||
| } on FormatException { | ||
| return null; | ||
| } | ||
| } | ||
|
elliette marked this conversation as resolved.
Resolved
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -13,6 +13,7 @@ import '../common/git_version_finder.dart'; | |
| import '../common/output_utils.dart'; | ||
| import '../common/package_state_utils.dart'; | ||
| import '../common/repository_package.dart'; | ||
| import '../common/version_placeholder.dart'; | ||
|
|
||
| /// Categories of version change types. | ||
| enum NextVersionType { | ||
|
|
@@ -112,9 +113,13 @@ class VersionAndChangelogValidator { | |
| /// and match the policy for the files changed, returning a list of resulting | ||
| /// error strings. | ||
| /// | ||
| /// [packageFiles] should be all of the files in [package], and is used to | ||
| /// check for version placeholders. | ||
| /// | ||
| /// If no errors are found, an empty list is returned. | ||
| Future<List<String>> validateChangelogAndVersion( | ||
| RepositoryPackage package, { | ||
| required Stream<File> packageFiles, | ||
| required bool checkForMissingChanges, | ||
| required bool ignorePlatformInterfaceBreaks, | ||
| }) async { | ||
|
|
@@ -159,6 +164,15 @@ class VersionAndChangelogValidator { | |
| } | ||
| } | ||
|
|
||
| final String? placeholderError = await _checkForVersionPlaceholders( | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It looks like _checkForVersionPlaceholders always allows {{NEXT_VERSION}} in lib/ whenever usesBatchRelease is true, even when the PR is the batch release PR itself (or when there are no version-bumping entries in pending_changelogs). I see the comment in the test mentioning that the sync-to-main PR also uses the override: batch- label and might merge in new placeholders from main. However, in that sync-to-main case, any new placeholder on main would come with a new pending changelog entry in pending_changelogs/ (whereas on the batch release PR itself, pending_changelogs/ has just been emptied and the version in pubspec.yaml is being bumped for release). If we allow {{NEXT_VERSION}} in lib/ when there are no version-bumping pending_changelogs entries (for example, on the batch release PR itself, or on a PR that only has a version: skip changelog), validate will pass in pre-submit and then publish will fail in post-submit when release_from_branches runs: Details test('validate passes on batch release PR with unreplaced {{NEXT_VERSION}} in '
'lib/ while publish fails on the same package state', () async {
const thisPackageName = 'a_package';
final RepositoryPackage package = createFakePackage(
thisPackageName,
packagesDir,
version: '1.1.0',
);
package.ciConfigFile.writeAsStringSync('release:\n batch: true\n');
package.pendingChangelogsDirectory.createSync();
package.changelogFile.writeAsStringSync('''
## 1.1.0
* Deprecate oldMethod.
''');
package.libDirectory.childFile('a_package.dart').writeAsStringSync('''
@Deprecated('Deprecated in v{{NEXT_VERSION}}.')
void oldMethod() {}
''');
gitProcessRunner.mockProcessesForExecutable['git-diff'] = <FakeProcessInfo>[
FakeProcessInfo(
MockProcess(
stdout: '''
packages/a_package/pubspec.yaml
packages/a_package/CHANGELOG.md
packages/a_package/lib/a_package.dart
''',
),
),
];
gitProcessRunner.mockProcessesForExecutable['git-show'] = <FakeProcessInfo>[
FakeProcessInfo(MockProcess(stdout: 'version: 1.0.0')),
];
final validateRunner = CommandRunner<void>('validate_test', 'test')
..addCommand(
ValidateCommand(
packagesDir,
processRunner: processRunner,
platform: mockPlatform,
gitDir: gitDir,
targetedValidators: <Validator>{Validator.version},
),
);
final List<String> validateOutput = await runCapturingPrint(validateRunner, <String>[
'validate',
'--base-sha=main',
'--packages=$thisPackageName',
'--pr-labels=override: batch-$thisPackageName',
]);
expect(
validateOutput,
containsAllInOrder(<Matcher>[
contains('Running for a_package'),
contains('No issues found!'),
]),
);
final publishRunner = CommandRunner<void>('publish_test', 'test')
..addCommand(PublishCommand(packagesDir, processRunner: processRunner, gitDir: gitDir));
Error? publishError;
final List<String> publishOutput = await runCapturingPrint(
publishRunner,
<String>['publish', '--packages=$thisPackageName'],
errorHandler: (Error e) {
publishError = e;
},
);
expect(publishError, isA<ToolExit>());
expect(
publishOutput,
containsAllInOrder(<Matcher>[
contains(
'Refusing to publish a package containing {{NEXT_VERSION}} placeholders. Replace them with the release version:\n'
' lib/a_package.dart',
),
contains('unreplaced {{NEXT_VERSION}} placeholder'),
]),
);
});
Member
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah good idea! We are now checking whether or not there is a pending changelog entry. If there is (e.g. on a feature PR opened against main, or the sync-to-main case) then version placeholders are allowed. If there isn't (e.g. on batch release PR) then version placeholders aren't allowed. Currently it's only checking for a pending changelog entry, not whether or not the entry specifies |
||
| package, | ||
| packageFiles, | ||
| usesBatchRelease: usesBatchRelease, | ||
| ); | ||
| if (placeholderError != null) { | ||
| errors.add(placeholderError); | ||
| } | ||
|
|
||
| final _CurrentVersionState versionState = await _getVersionState( | ||
| package, | ||
| pubspec: pubspec, | ||
|
|
@@ -649,6 +663,82 @@ ${_indentation}The first version listed in CHANGELOG.md is $fromChangeLog. | |
| return versionChanged; | ||
| } | ||
|
|
||
| /// Returns an error string if any of [packageFiles] contain a | ||
| /// [nextVersionPlaceholder] that won't be replaced automatically, printing | ||
| /// the offending files. | ||
| /// | ||
| /// Placeholders are only replaced by the batch release tooling, and only in | ||
| /// [VersionPlaceholderScope.replaceable] files, so they are not allowed in | ||
| /// packages that don't use batch release, in PRs without a pending changelog | ||
| /// entry, or in any other files. | ||
| Future<String?> _checkForVersionPlaceholders( | ||
| RepositoryPackage package, | ||
| Stream<File> packageFiles, { | ||
| required bool usesBatchRelease, | ||
| }) async { | ||
| final bool hasPendingChangelogs = usesBatchRelease && _hasPendingChangelogs(package); | ||
| final path.Context fsPath = package.directory.fileSystem.path; | ||
| final placeholderPaths = <String>[ | ||
| for (final VersionPlaceholderFile f in await findVersionPlaceholderFiles( | ||
| package.directory, | ||
| packageFiles, | ||
| scope: VersionPlaceholderScope.all, | ||
| )) | ||
| if (!hasPendingChangelogs || | ||
| !VersionPlaceholderScope.replaceable.includes( | ||
| fsPath.relative(f.file.path, from: package.directory.path), | ||
| fsPath, | ||
| )) | ||
| relativePosixPath(f.file, from: package.directory, platformContext: _path), | ||
| ]; | ||
| if (placeholderPaths.isEmpty) { | ||
| return null; | ||
| } | ||
| final String reason = _versionPlaceholderErrorMessage( | ||
| usesBatchRelease: usesBatchRelease, | ||
| hasPendingChangelogs: hasPendingChangelogs, | ||
| ); | ||
| printError( | ||
| '$_indentation$reason\n' | ||
| '${_indentation}Found $nextVersionPlaceholder in:\n' | ||
| '${placeholderPaths.map((String p) => '$_indentation $p').join('\n')}', | ||
| ); | ||
| return 'Unreplaced $nextVersionPlaceholder placeholder.'; | ||
| } | ||
|
|
||
| /// Returns the explanation for why unreplaced [nextVersionPlaceholder]s are | ||
| /// not allowed. | ||
| String _versionPlaceholderErrorMessage({ | ||
| required bool usesBatchRelease, | ||
| required bool hasPendingChangelogs, | ||
| }) { | ||
| if (!usesBatchRelease) { | ||
| return 'This package does not use batch release, so $nextVersionPlaceholder ' | ||
| 'placeholders will not be replaced automatically. Use the actual ' | ||
| 'version instead.'; | ||
| } else if (!hasPendingChangelogs) { | ||
| return 'Using $nextVersionPlaceholder is only allowed in PRs with a ' | ||
| 'pending changelog entry. To resolve, create a pending changelog entry ' | ||
| 'or remove $nextVersionPlaceholder instead.'; | ||
| } else { | ||
| return '$nextVersionPlaceholder placeholders are only supported ' | ||
| 'in Dart files in lib/.'; | ||
| } | ||
| } | ||
|
|
||
| /// Returns true if [package] has at least one valid pending changelog entry. | ||
| /// | ||
| /// Entries with `version: skip` count, since their placeholders will be | ||
| /// replaced by the next release that does change the version. | ||
| bool _hasPendingChangelogs(RepositoryPackage package) { | ||
| try { | ||
| return package.getPendingChangelogs().isNotEmpty; | ||
| } on FormatException { | ||
| // Invalid pending changelogs are reported separately. | ||
| return false; | ||
| } | ||
| } | ||
|
|
||
| Future<String> _getRelativePackagePath(RepositoryPackage package) async { | ||
| return relativePosixPath(package.directory, from: _repoRoot, platformContext: _path); | ||
| } | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just curious, when does the tool changelog actually bump?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm based on the history on Github and pub, it looks like it gets bumped after being published, and I'm guessing publishing is supposed to happen manually.
However, I noticed we are on
[0.14.4+1](https://pub.dev/packages/flutter_plugin_tools/versions/0.14.4+1)on pub,0.14.4+3in the pubspec, and then had both0.14.4+4andNEXTentries in the changelog. I removedNEXTso now we only have0.14.4+4in the changelog, but probably we should establish a clearer process here around version bumps / publishing.