Skip to content

Commit

Permalink
Minor verbiage changes about MVS + bzlmod
Browse files Browse the repository at this point in the history
This paragraph was a bit misleading, particularly if you are skimming the docs rather than reading top to bottom. Out of context, it sounds like coexistence of multiple major versions of the same module works, when really the next paragraph clarifies that its the opposite.

I tweaked things a tad to make it comparison to Go a bit more obvious at the start of the paragraph.

I think it might be worth reworking this entire page to be less dependent on Go semantics and simple explain MVS + bzlmod semantics for bzlmod directly (I say this as a bazel user without a ton of go modules experience, so the comparisons aren't useful for all audiences).

Closes #17766.

PiperOrigin-RevId: 516532030
Change-Id: Ie8a327511c9c26697b2f45501ebf6bbc2b0e2944
  • Loading branch information
andrewhamon authored and copybara-github committed Mar 14, 2023
1 parent 9eadedb commit 43ae7c2
Showing 1 changed file with 14 additions and 14 deletions.
28 changes: 14 additions & 14 deletions site/en/external/module.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,19 +91,19 @@ flag to explicitly allow the yanked version.

## Compatibility level

MVS's assumption about backwards compatibility works because it treats backwards
incompatible versions of a module as a separate module. In terms of SemVer, that
means `A 1.x` and `A 2.x` are considered distinct modules, and can coexist in
the resolved dependency graph. This is, in turn, made possible by encoding the
major version in the package path in Go, so there aren't any compile-time or
linking-time conflicts.

Bazel cannot provide such guarantees, so it needs the "major version" number in
order to detect backwards incompatible versions. This number is called the
*compatibility level*, and is specified by each module version in its `module()`
directive. With this information, Bazel can throw an error when it detects that
versions of the same module with different compatibility levels exist in the
resolved dependency graph.
In Go, MVS's assumption about backwards compatibility works because it treats
backwards incompatible versions of a module as a separate module. In terms of
SemVer, that means `A 1.x` and `A 2.x` are considered distinct modules, and can
coexist in the resolved dependency graph. This is, in turn, made possible by
encoding the major version in the package path in Go, so there aren't any
compile-time or linking-time conflicts.

Bazel, however, cannot provide such guarantees, so it needs the "major version"
number in order to detect backwards incompatible versions. This number is called
the *compatibility level*, and is specified by each module version in its
`module()` directive. With this information, Bazel can throw an error when it
detects that versions of the same module with different compatibility levels
exist in the resolved dependency graph.

## Overrides

Expand Down Expand Up @@ -190,4 +190,4 @@ dependencies. This helps prevent accidental breakages due to changes in
transitive dependencies.

[Module extensions](/external/extension) can also introduce additional repos
into the visible scope of a module.
into the visible scope of a module.

0 comments on commit 43ae7c2

Please sign in to comment.