How to support Bazel module versioning

[cgrindel]

Type of discussion.

I just want to chat

Tell us more.

Background

Bazel module versions consist of two parts: the version string and the compatibility level. The version string uniquely identifies a release and is used to sort releases. The compatibility level is the "major version" number.

There is no requirement for the compatibility level to be represented in the version string. It is specified as a separate value with each module release. The following are some examples of Bazel module declarations that highlight the inability to extract the compatibility level directly from the version string.

# The compatibility_level for this declaration defaults to 0.
module(name = "my-module", version = "1.0.0")

# Another example where the compatibility level is not embedded in the version string.
module(name = "my-module", version = "0.16.0", compatibility_level = 1)

# One more example not using a SemVer version string
module(name = "my-module", version = "20230125.3", compatibility_level = 5)

To summarize, the version string uniquely identifies the release, but the complete information about the release version resides in the registry.

Issues Related to Supporting Bazel Module Versions in Renovate

Two primary issues need to be addressed to support Bazel module versions in Renovate.

1. How to represent the complete version (version string and compatibility level) in the APIs.
2. How to resolve a version string to a complete Bazel module version that includes the compatibility level.

How to Represent a Bazel Module Version

The Renovate APIs use a string value to represent a version. There is no canonical string representation for a Bazel module version (version string plus compatibility level). We could update the Renovate APIs to expect a customizable version struct. At first blush, that seems like a pretty big change. Unless there are other benefits to doing that kind of rework outside the scope of this discussion, it does not seem worthwhile.

The alternative is to design a string representation of a Bazel module version. The following are some options:

• Super Compact - <version>|<compatibility_level>
  • Ex: 1.0.0|0, 0.16.0|1, 20230125.3|5
  • This is compact and reasonably user-friendly.
• JSON String
  • Ex: {"version": "1.0.0", compatibility_level: 0}
  • Standard format that handles any weird encoding.
  • More verbose; not sure what the UI implications would be.
• Lightly Delimited Fields - v: "<version>", cl: <compatibility_level>
  • Ex: v: "1.0.0", cl: 0
  • The version string would be a JSON-encoded string. The compatibility level would be a JSON-encoded integer.
  • Attempts to balance compactness with a user-friendly string representation.

How to Resolve a Version String to a Bazel Module Version

Let's look at this concerning the three primary APIs: Datasource, Versioning, and Manager.

• bazel Datasource
  • The datasource has full access to the configured registries. As a result, it can construct a complete Bazel module version.
• bazel-module Versioning
  • The versioning implementation can easily be updated to parse the version string and compatibility level from the string.
• bazel-module Manager
  • The manager retrieves version string values from MODULE.bazel files. Ex: bazel_dep(name = "rules_cc", version = "0.0.1")
  • The version string uniquely identifies the version in a particular registry. However, it does not provide a compatibility level.
  • Hence, the manager cannot construct a fully qualified Bazel module version.

The following are some options that I think are worth consideration.

Option 1: Manager Resolves the Versions

In this scenario, the manager would resolve each version string to a fully-qualified Bazel module version. This would require the manager to access the configured registries. This could be done by allowing the manager to leverage the existing datasources or via some custom mechanism. I think leveraging the existing datasources makes the most sense, as it could leverage any caching that may already be implemented.

Option 2: Manager Returns Version String Values, External Mechanism Resolves the Versions

In this scenario, the manager would not change. It would return the version strings extracted from the MODULE.bazel file. A separate mechanism would resolve the version strings to fully-qualified Bazel module versions. This separate mechanism would be activated via a manager configuration value. Ideally, this resolution mechanism would work with the results from configured datasources.

Conclusion

Let me know what you think. I am curious to hear other ideas on how to tackle these issues.

[rarkins]

Some simple questions to begin with:

1. Is the registry itself the "single source of truth" for mapping a version to its compatibility level?
2. If so, does it mean that you could leave compatibility level out completely when declaring such dependencies?
3. If so, why would anyone add compatibility level? It doesn't seem helpful
4. How will this change Renovate's behavior? For example let's say that Renovate updates from 1.0.0 to 2.0.0 but the module declares the compatibility level remains the same. Should Renovate not treat it as a "major" update?

BTW this may be a time to separate the related concepts of "breaking" and "major". I think that if a module updated from 1.0.0 to 2.0.0 but said it's the same compatibility level, maybe we still call it a "major" update but breaking=false in metadata. Similarly in semver, you can have non-major 0.x updates which are breaking.

[viceice]

if we need the compabillity, we could encode it like apt versioning. eg 1:2.0.1

[cgrindel]

Is the registry itself the "single source of truth" for mapping a version to its compatibility level?

Yes.

If so, does it mean that you could leave compatibility level out completely when declaring such dependencies?

Dependencies cannot specify the compatibility level explicitly. They can only specify the version string. The version string uniquely identifies the release. The release has a declared compatibility level.

If so, why would anyone add compatibility level?

The compatibility level is the major version. Bazel module version strings typically fall into two formats: SemVer and dates (e.g. 20230125.3). While SemVer does support the idea of a major version, the date strings do not. Hence, when a release is published to a registry, the publisher specifies the version string, which uniquely identifies the release for the module, and the compatibility level, which designates the major version number.

Regarding why Bazel supports compatibility level, it relates to version resolution. At a high level, multiple version declarations for a module with the same compatibility level will resolve to a single version. For instance, if the dependency graph for a project has declarations 1.2.0, 1.2.1, and 2.0.0 for module rules_foo where the 1.x releases have the same compatibility level and the 2.x release has a different compatibility level, Bazel will resolve these to two copies of the module: 1.2.1 and 2.0.0.

How will this change Renovate's behavior?

The goal is to support Renovate's heuristics for handling major version bumps. Technically, without the compatibility level, there is no fool-proof way to know major version.

For example let's say that Renovate updates from 1.0.0 to 2.0.0 but the module declares the compatibility level remains the same. Should Renovate not treat it as a "major" update?

Great question. Technically, yes. However, I would argue that this is a mistake on publisher's part.

[rarkins]

If so, does it mean that you could leave compatibility level out completely when declaring such dependencies?

Dependencies cannot specify the compatibility level explicitly. They can only specify the version string. The version string uniquely identifies the release. The release has a declared compatibility level.

I thought that strings like the following were from package files the user writes, but is that not the case?

# Another example where the compatibility level is not embedded in the version string.
module(name = "my-module", version = "0.16.0", compatibility_level = 1)

Is this example instead where the module author themselves are declaring the compatibility_level?

The goal is to support Renovate's heuristics for handling major version bumps. Technically, without the compatibility level, there is no fool-proof way to know major version.

So the idea is to use compatibility_level to determine whether it's a "major" update or non-major? even if it's e.g. 0.1.0 to 1.0.0 while keeping same compatibility_level (which in semver is a major) or 20230301.1 to 2023040.1 with a change in compatibility_level?

For example let's say that Renovate updates from 1.0.0 to 2.0.0 but the module declares the compatibility level remains the same. Should Renovate not treat it as a "major" update?

Great question. Technically, yes. However, I would argue that this is a mistake on publisher's part.

So you expect when they use semver that any major version changes except sometimes 0.x -> 1.0.0 would bump compatibility_level?

[cgrindel]

Is this example instead where the module author themselves are declaring the compatibility_level?

That is correct. The module author writes the module(...) declarations. The clients who want to use the module write the bazel_dep(...) declarations.

So the idea is to use compatibility_level to determine whether it's a "major" update or non-major? even if it's e.g. 0.1.0 to 1.0.0 while keeping same compatibility_level (which in semver is a major) or 20230301.1 to 2023040.1 with a change in compatibility_level?

Yes. However, in the SemVer case, I would argue that the module maintainer has introduced a bug if they increment the major version in the version string and not increment the compatibility level.

So you expect when they use semver that any major version changes except sometimes 0.x -> 1.0.0 would bump compatibility_level?

Yes.

[rarkins]

So if I'm understanding right, the compatibility_level is needed only to know if a change is breaking or not. For Semver-tagged modules, you could almost say it's not needed, because we can use the major number as an indicator and produce PRs according to user expectations.

A good example to focus on is calendar-based versioning and now compatibility_level awareness would change Renovate's behavior. Without greater awareness, Renovate would need to treat these as breaking changes whenever the day changed, and would have branches like renovate/module-name-20230415.x. So the first change would be that we'd want the branch to be like renovate/module-name-1.x if compatibility_level=1.

One way to achieve this would be to embed the compatibility level as the major version in such non-semver releases, e.g. call them 1.20230415.1 and then the day becomes the minor part. I'm not sure if this "hack" is so good though.

Important point to reiterate: Renovate today doesn't have first-class support for "breaking" concepts. It approximates it from major/non-major.

Here is the part where updates are classified into "buckets" such as major and non-major: https://github.com/renovatebot/renovate/blob/main/lib/workers/repository/process/lookup/bucket.ts

It's called from here:

renovate/lib/workers/repository/process/lookup/index.ts

Lines 251 to 257 in 735129b

	const bucket = getBucket(
	config,
	// TODO #7154
	currentVersion!,
	release.version,
	versioning
	);

So at that point we definitely could pass release.compatibilityLevel if we had it.

[cgrindel]

Interesting. So, if we had the compatibility level on the release, we could avoid the resolution step I mentioned previously in this thread. 😎

Just a thought. A field called compatibilityLevel seems very specific for the Bazel module case. Perhaps the field should be called majorVersion. If a release does not populate the field, Renovate would fallback to the current mechanism of getting the major version from the version string.

[rarkins]

I worry that might have some strange side effects. Also quite confusing if e.g the version is 1.0.0 but compatiblity_level=2 (e.g. they changed something between v0 and v1)

[HonkingGoose]

If that field is specific to Bazel, it should have a unique name. We already have general config options with major in their name.

[rarkins]

I think it's a concept we could potential use elsewhere