Add check for yanked version (bazelbuild#3621)

- The latest version of a module should not be yanked.
- Unless the module is marked as deprecated via `"deprecated":
"<reason>"`.

Fixes bazelbuild#3604

docs/README.md

@@ -158,6 +158,8 @@ For example, in `zlib`'s [metadata.json](https://github.com/bazelbuild/bazel-cen
 
 A Bzlmod user's build will start to fail if the yanked version is in the resolved dependency graph, and the yanked reason will be presented in the error message. The user can choose to upgrade the dependency or they can bypass the check by specifying the `--allow_yanked_versions` flag or the `BZLMOD_ALLOW_YANKED_VERSIONS` environment variable. Check [the documentation](https://bazel.build/reference/command-line-reference#flag--allow_yanked_versions) to learn how to use them.
 
+The latest version of a module should not be yanked. If you do need to yank the latest version because the module is deprecated, you should add `"deprecated": "<reason>"` in its `metadata.json` file.
+
 ## Versions format
 
 Bazel has a diverse ecosystem and projects using various versioning schemes, check [Bzlmod's version specification](https://bazel.build/external/module#version_format). If you need to update a module with only patch file changes, you can add `.bcr.<N>` suffix to the version number.

metadata.schema.json

@@ -49,6 +49,11 @@
       "yanked_versions": {
         "type": "object",
         "additionalProperties": true
+      },
+      "deprecated": {
+        "type": "string",
+        "description": "The reason this module is deprecated. If set, the latest version can be yanked.",
+        "additionalProperties": true
       }
     },
     "additionalProperties": false,

modules/io_opentracing_cpp/metadata.json

@@ -14,5 +14,6 @@
     ],
     "yanked_versions": {
         "1.6.0": "use [email protected] instead"
-    }
+    },
+    "deprecated": "use opentracing-cpp instead"
 }

modules/rules_directory/metadata.json

@@ -17,5 +17,6 @@
     "yanked_versions": {
       "0.0.1": "Code has been moved into bazel_skylib. Use the directory rules in bazel_skylib instead.",
       "0.0.2": "Code has been moved into bazel_skylib. Use the directory rules in bazel_skylib instead."
-    }
+    },
+    "deprecated": "Code has been moved into bazel_skylib. Use the directory rules in bazel_skylib instead."
 }

tools/bcr_validation.py

@@ -523,6 +523,16 @@ def validate_all_metadata(self):
                         f"but it's recorded in {module_name}'s metadata.json file.",
                     )
                     has_error = True
+
+            latest_version = metadata["versions"][-1]
+            if not metadata.get("deprecated") and latest_version in metadata.get("yanked_versions", {}):
+                self.report(
+                    BcrValidationResult.FAILED,
+                    f"The latest version ({latest_version}) of {module_name} should not be yanked, "
+                    f"please make sure a newer version is available before yanking it.",
+                )
+                has_error = True
+
         if not has_error:
             self.report(BcrValidationResult.GOOD, "All metadata.json files are valid.")