[Proposal] Change BCR-only version naming pattern

[armandomontanez]

I'd like to rethink our BCR-only release naming, in part to support bazelbuild/bazel#23461 and other floating releases that don't map to official releases.

Proposal

Recommend +bcr.<N>.<short Git SHA>, where the .<short Git SHA> is an optional indicator for intermediate releases that aren't associated with an official release. Note that <N> should always be incremented to ensure version ordering is maintained, as git hashes aren't suitable for semver ordering.

Examples:

• 1.234.456 - An official release with no BCR-only changes.
• 0.0.1-RC1 - An official release candidate with no BCR-only changes.
• 1.234.456.AS-1333.2024.09.14 - An official release that doesn't strictly follow semver.
• 1.234.456+bcr.1 - An official release that involves a BCR-related patch.
• 1.2.3-RC2+bcr.1 - An official release candidate that involves a BCR-related patch.
• 1.0.1-develop+bcr.17.dd7336eca - The 17th BCR-only release for the develop channel for 1.0.1.
• 2.0.3+bcr.1.dd7336eca - A BCR-only release for a floating commit after the v2.0.3 release but before the next official release.
• 1.234.456.AS-1333.2024.09.14+bcr.1 - An official release that doesn't strictly follow semver and involves a BCR-related patch.

Justification

Semver major.minor.patch has specific semantic intent for the patch portion of the version string. While placing . separators in/following the patch string are not explicitly prohibited, semver requests patch is an integer and prescribes ways to append additional information:

• A pre-release version may be denoted by appending a hyphen
• Build metadata may be denoted by appending a plus sign

While many projects elect to use the hyphen to denote pre-releases (e.g. -RC1, -develop, -pre.1), using the plus in official releases of source code is quite rare (anecdotally). This means it's less likely that BCR versions will ever collide with this nomenclature, and it's much more visually distinct when a given version has BCR-only changes.

[Wyverald]

The justification part doesn't make sense to me, since Bazel module versions are a strict superset of SemVer, not the other way around. So version strings on the BCR are intentionally not always valid SemVer; conversely, any SemVer is a valid Bazel module version. See https://bazel.build/external/module#version_format for more info.

The other problem with this proposal is that it breaks the invariant that "two SemVer versions a and b compare a < b if and only if the same holds when they're compared as Bazel module versions". In SemVer, 1.0.0+bcr.1 compares equal to 1.0.0+bcr.2. With this proposal, Bazel would consider one to be newer than the other.

[fmeum]

https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/bazel/bzlmod/Version.java;l=65

[armandomontanez]

I ended up experimenting with some naming stuff and it looks like the +foo part doesn't appear to be properly handled somewhere in Bazel:

https://buildkite.com/bazel/bcr-presubmit/builds/10061#01946779-0b68-4633-9a7b-b5e869a90846

It seems to be related to stripping the +foo part as some part of version resolution, which implicitly creates an inequality since the stripped version doesn't match the actual version string. I don't think fixing this matters that much since any use will be inherently incompatible with some versions of Bazel.

Either way, .bcr.20250113-4b6e6475 was an adequate suffix for a BCR-only release of a true Bazel module. For modules that patch in build files via diffs, the date/commit hash isn't as helpful, and there's still a need for <N>.

Perhaps we can close this discussion. There's probably not a good one-size-fits-all answer and fragmentation is inevitable anyway.

[Wyverald]

I ended up experimenting with some naming stuff and it looks like the +foo part doesn't appear to be properly handled somewhere in Bazel:

This is intentional: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/bazel/bzlmod/Version.java;l=54-59;drc=a8a2c0c1fa063a0bba4e7222a1b1d2c8a4e0e632

Either way, .bcr.20250113-4b6e6475 was an adequate suffix for a BCR-only release of a true Bazel module.

See also the guidelines that we just posted recently: https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md#pseudo-versions

Although it should be noted that having the .bcr. bit in the pseudo-version does emphasize that the version doesn't exist upstream. ISTM that it shouldn't matter much, since no official release should look like 1.2.3.20250318.whatever anyway, so anything looking like a pseudo-version can probably be assumed to be a BCR-only version.

[armandomontanez]

Oh cool, thanks for adding that!

Minor note that I found using YYYYMMDDhhmmss can cause Java to throw a NumberFormatException:

https://buildkite.com/bazel/bcr-presubmit/builds/10060#0194675c-09e0-4a6d-b19e-e79f2d1f7623

Caused by: java.lang.NumberFormatException: For input string: "20250113215903"
    at java.base/java.lang.NumberFormatException.forInputString(Unknown Source)

I can send out a PR to update that bit.

[fmeum]

bazelbuild/bazel#24945 should have fixed this, but we never cherry-picked it @meteorcloudy @Wyverald