manifest: clarify schema version check with cosmetic renames

As found in the review of zephyrproject-rtos#904 (migration from pkwalify to jsonschema),
the schema version check can be confusing.

- Add a couple sentences in MAINTAINERS.rst to clearly state what this
  version check actually performs and achieves and when (not) to bump the
  version.

- Rename "min_version" to "manifest_version" and swap the perspective

"min" and "max" are relative terms, ambiguous when losing track of the
point of view. "min_version" stood for
"minimum_west_version_needed_to_read_this_manifest". But this is the
manifest perspective, which is confusing when reading west code which is
the opposite point of view.  A given _version_ of west code is never going
to change when reading it or running it! So, flip the perspective and
look at things from the west point of view when in the west code: rename
the also vague _SCHEMA_VER to _MAX_SUPPORTED_SCHEMA_VER.

Signed-off-by: Marc Herbert <[email protected]>

Author: marc-hb

MAINTAINERS.rst

@@ -144,10 +144,15 @@ Summary of what happens:
    Decide if west.manifest.SCHEMA_VERSION needs an update:
 
    - SCHEMA_VERSION should be updated to X.Y if release vX.Y will have manifest
-     syntax changes that earlier versions of west cannot parse.
+     syntax changes that earlier versions of west cannot parse. The version
+     check causes earlier west versions to abort and forces users to upgrade
+     west to use manifests with new syntax or features.
 
    - SCHEMA_VERSION should *not* be changed for west vX.Y if the manifest
-     syntax is fully compatible with what west vX.(Y-1) can handle.
+     syntax is fully compatible with what west vX.(Y-1) can handle. This would
+     force some users to upgrade west unnecessarily when trying to use
+     manifests wrongly presenting themselves as using new syntax/features that
+     have not actually changed.
 
    If you want to change SCHEMA_VERSION, send this as a pull request to the
    main branch and get it reviewed and merged. (This requires a PR and review

src/west/manifest.py

@@ -51,7 +51,7 @@
 #: Git ref space used by west for internal purposes.
 QUAL_REFS_WEST = 'refs/west/'
 
-#: The latest manifest schema version supported by this west program.
+#: The highest manifest schema version supported by this west version.
 #:
 #: This value will change whenever a new version of west includes new
 #: manifest file features not supported by earlier versions of west.
@@ -204,7 +204,7 @@ class _defaults(NamedTuple):
 _DEFAULT_REV = 'master'
 _WEST_YML = 'west.yml'
 _SCHEMA_PATH = os.path.join(os.path.dirname(__file__), "manifest-schema.yml")
-_SCHEMA_VER = parse_version(SCHEMA_VERSION)
+_MAX_SUPPORTED_SCHEMA_VER = parse_version(SCHEMA_VERSION)
 _EARLIEST_VER_STR = '0.6.99'  # we introduced the version feature after 0.6
 _VALID_SCHEMA_VERS = [
     _EARLIEST_VER_STR,
@@ -616,17 +616,17 @@ def validate(data: Any) -> dict[str, Any]:
         #
         #  version: 0.8
         if not isinstance(data['version'], str):
-            min_version_str = str(data['version'])
+            manifest_version_str = str(data['version'])
             casted_to_str = True
         else:
-            min_version_str = data['version']
+            manifest_version_str = data['version']
             casted_to_str = False
 
-        min_version = parse_version(min_version_str)
-        if min_version > _SCHEMA_VER:
-            raise ManifestVersionError(min_version_str)
-        if min_version_str not in _VALID_SCHEMA_VERS:
-            msg = f'invalid version {min_version_str}; must be one of: ' + ', '.join(
+        manifest_version = parse_version(manifest_version_str)
+        if manifest_version > _MAX_SUPPORTED_SCHEMA_VER:
+            raise ManifestVersionError(manifest_version_str)
+        if manifest_version_str not in _VALID_SCHEMA_VERS:
+            msg = f'invalid version {manifest_version_str}; must be one of: ' + ', '.join(
                 _VALID_SCHEMA_VERS
             )
             if casted_to_str: