Improve FlutterVersion docs #167674
Improve FlutterVersion docs #167674
Conversation
| /// The Flutter version used to compile the app. | ||
| /// The value is a [semantic versioning](https://semver.org/) string representing the | ||
| /// version of Flutter used to compile the app, possibly followed by whitespace and | ||
| /// other version and build details. | ||
| static const String? version = |
There was a problem hiding this comment.
Flutter doesn't use semver, so this isn't accurate.
In particular there's no greater amount of breakage implied when the first number in the version increases, and there's no promise that no breaking API changes happen when the first number doesn't increase. See the list of Flutter breaking changes:
https://docs.flutter.dev/release/breaking-changes
There was a problem hiding this comment.
Here it says:
Flutter version: The version number of the Flutter SDK (for example, 3.0.0, 2.10.5). This follows semantic versioning, indicating the significance of changes between releases.
There was a problem hiding this comment.
Hmm, that's a bug in the website, then — it'd be good to correct that.
The main point of Semantic Versioning, aka https://semver.org/, is that the first number in the version (the "major" version number) gets incremented when there's an incompatible API change. If Flutter followed that convention, then every release that's listed on https://docs.flutter.dev/release/breaking-changes would be a new major version. Instead of 1.20 it'd be 2.0.0, instead of 1.22 it'd be 3.0.0, and by now it'd be something like 17.0.0 instead of 3.29. As you can see, that's not the numbering that Flutter uses.
A developer who expects Semantic Versioning is going to be surprised when they upgrade from, for example, 3.27.x to 3.29.x and then run into one of the 6 different breaking changes listed for 3.29 on that page. So setting that expectation would be likely to lead to disappointment.
| /// The value is a [semantic versioning](https://semver.org/) string representing the | ||
| /// version of the Dart runtime used to compile the app, possibly followed by whitespace | ||
| /// and other version and build details. | ||
| /// | ||
| /// On `dart:io` platforms it is more reliable to use [Platform.version]. | ||
| static const String? dartVersion = |
There was a problem hiding this comment.
Each doc comment should start with a short summary. See the style guide:
https://dart.dev/effective-dart/documentation#do-start-doc-comments-with-a-single-sentence-summary
For example on Platform.version:
https://api.dart.dev/dart-io/Platform/version.html
there's a paragraph similar to the first paragraph here — but before that, there's a much shorter paragraph, which is the summary.
This improves the docs for the FlutterVersion class. In particular, it provides more context on what the various strings contain, and it includes some more guidance for using
FlutterVersion.dartVersion.Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.