Make version documentation clearer. (#27278)

Currently, in pubspec.yaml, semver.org is referred to for more about versioning.
However, the versionCode/versionName could differ on different platforms (iOS, Android, Dart).

This adds more clear and complete information that could help users to understand it better.

See: #27251

packages/flutter_tools/lib/src/base/user_messages.dart

@@ -281,4 +281,12 @@ class UserMessages {
       'This can happen when you have multiple copies of flutter installed. Please check '
       'your system path to verify that you are running the expected version (run '
       '\'flutter --version\' to see which flutter is on your path).\n';
+  String invalidVersionSettingHintMessage(String invalidVersion) =>
+      'Invalid version $invalidVersion found, default value will be used.\n'
+      'In pubspec.yaml, a valid version should look like: build-name+build-number.\n'
+      'In Android, build-name is used as versionName while build-number used as versionCode.\n'
+      'Read more about Android versioning at https://developer.android.com/studio/publish/versioning\n'
+      'In iOS, build-name is used as CFBundleShortVersionString while build-number used as CFBundleVersion.\n'
+      'Read more about iOS versioning at\n'
+      'https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html\n';
 }

packages/flutter_tools/lib/src/flutter_manifest.dart

@@ -9,6 +9,7 @@ import 'package:meta/meta.dart';
 import 'package:yaml/yaml.dart';
 
 import 'base/file_system.dart';
+import 'base/user_messages.dart';
 import 'base/utils.dart';
 import 'cache.dart';
 import 'convert.dart' as convert;
@@ -76,14 +77,22 @@ class FlutterManifest {
   /// The string value of the top-level `name` property in the `pubspec.yaml` file.
   String get appName => _descriptor['name'] ?? '';
 
+  // Flag to avoid printing multiple invalid version messages.
+  bool _hasShowInvalidVersionMsg = false;
+
   /// The version String from the `pubspec.yaml` file.
   /// Can be null if it isn't set or has a wrong format.
   String get appVersion {
     final String version = _descriptor['version']?.toString();
-    if (version != null && _versionPattern.hasMatch(version))
-      return version;
-    else
-      return null;
+    if (version != null) {
+      if (_versionPattern.hasMatch(version)) {
+        return version;
+      } else if (!_hasShowInvalidVersionMsg) {
+        printStatus(userMessages.invalidVersionSettingHintMessage(version), emphasis: true);
+        _hasShowInvalidVersionMsg = true;
+      }
+    }
+    return null;
   }
 
   /// The build version name from the `pubspec.yaml` file.

packages/flutter_tools/templates/app/pubspec.yaml.tmpl

@@ -10,7 +10,11 @@ publish_to: 'none'
 # followed by an optional build number separated by a +.
 # Both the version and the builder number may be overridden in flutter
 # build by specifying --build-name and --build-number, respectively.
-# Read more about versioning at semver.org.
+# In Android, build-name is used as versionName while build-number used as versionCode.
+# Read more about Android versioning at https://developer.android.com/studio/publish/versioning
+# In iOS, build-name is used as CFBundleShortVersionString while build-number used as CFBundleVersion.
+# Read more about iOS versioning at
+# https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 version: 1.0.0+1
 {{/withPluginHook}}
 

packages/flutter_tools/templates/module/common/pubspec.yaml.tmpl

@@ -6,7 +6,11 @@ description: {{description}}
 # followed by an optional build number separated by a +.
 # Both the version and the builder number may be overridden in flutter
 # build by specifying --build-name and --build-number, respectively.
-# Read more about versioning at semver.org.
+# In Android, build-name is used as versionName while build-number used as versionCode.
+# Read more about Android versioning at https://developer.android.com/studio/publish/versioning
+# In iOS, build-name is used as CFBundleShortVersionString while build-number used as CFBundleVersion.
+# Read more about iOS versioning at
+# https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 #
 # This version is used _only_ for the Runner app, which is used if you just do
 # a `flutter run` or a `flutter make-host-app-editable`. It has no impact