You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: blog/_posts/2021-02-16-preventing-version-conflicts-with-versionscheme.md
+17-13Lines changed: 17 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ One of the things that makes Scala powerful and fun to use is its library ecosys
9
9
10
10
However, the library ecosystem is not without problems. A library that you pulled could depend on other libraries, and the transitive dependencies could cause version conflicts. Here's a quick example of a Scala project that uses Akka HTTP, a Postgres database, and JSON. Its build declares two library dependencies, `akka-http-circe` and `doobie-postgres-circe`:
@@ -22,7 +22,7 @@ sbt loads the project build, the project compiles successfully, but when you try
22
22
23
23
What happens here is that one of the transitive dependencies of `akka-http-circe` depends on `circe-core` version 0.11.1, and another transitive dependency of `doobie-postgres-circe` depends on `circe-core` version 0.13.0. Here's an excerpt of the output of sbt’s `dependencyTree` task:
@@ -32,15 +32,15 @@ What happens here is that one of the transitive dependencies of `akka-http-circe
32
32
33
33
Unfortunately, these two versions of Circe are not binary compatible. Such version conflicts are common in a dependency graph of any practical size. The problem is that we carefully program our code using a statically checked type system, but when it comes to production code we accept swapping out the JAR file with something that our dependency resolver like Coursier and Apache Ivy selected on a whim.
34
34
35
-
The Scala Center, Alexandre Archambault (author of Coursier), and Eugene Yokota have been working on a solution to improve this situation so that we can be confident about creating libraries, and using them.
35
+
The Scala Center, Alexandre Archambault (author of Coursier), and Eugene Yokota have been working on a solution to reliably detect such conflicts at compilation time.
36
36
37
37
In the next section, we will explain the mechanism that was in place so far in sbt to address this issue, and we will discuss its limits. Then, we will introduce a new solution, which requires library authors to declare the versioning scheme of their libraries with a new sbt key, `versionScheme`.
38
38
39
39
## Eviction warnings
40
40
41
41
Actually this is not the first time we have thought of this issue. In 2014, we added [eviction warning][1] feature to sbt 0.13.6. When you have two candidate versions 0.11.1 and 0.13.0, and when it picks 0.13.0, 0.11.1 is said to be "evicted".
42
42
43
-
~~~text
43
+
~~~
44
44
sbt:killer-app> evicted
45
45
[warn] Found version conflict(s) in library dependencies; some are suspected to be binary incompatible:
46
46
[warn] * io.circe:circe-core_2.12:0.13.0 is selected over 0.11.1
@@ -67,11 +67,11 @@ Given a version number `major.minor.patch`, you MUST increment the:
67
67
68
68
- When the `major` version is `0`, a minor version increment MAY contain **both source and binary breakages**, but a patch version increment MUST remain **binary compatible**.
69
69
70
-
We call this Early SemVer, because according to the [Semantic Versioning Spec][2] there are no guarantees between any versions when the major version is `0`. In the Scala library ecosystem, though, we often start guaranteeing binary compatibility for `0.y.z` like sbt 0.13 and Scala.js 0.6.
70
+
We call this "Early" SemVer, because according to the [Semantic Versioning Spec][2] there are no guarantees between any versions when the major version is `0`. In the Scala library ecosystem, though, we often start guaranteeing binary compatibility for `0.y.z` like sbt 0.13 and Scala.js 0.6.
71
71
72
72
Unfortunately, it is not an easy task to know whether a change on public API broke source or binary compatibility. The Scala Center contracted Alexandre Archambault to create [sbt-version-policy][5]. This plugin helps library authors to self-check a version scheme. To use this, add the following to your `project/plugins.sbt`:
This plugin provides a task called `versionPolicyCheck`, which you can call in the CI (continuous integration) server. The task performs an automatic binary compatibility check.
85
+
This plugin provides a task called `versionPolicyCheck`, which you can call in the continuous integration server.
86
86
87
-
~~~text
87
+
~~~
88
88
> versionPolicyCheck
89
89
~~~
90
90
91
+
The task checks that the current state of the project is binary compatible with the previous release, and fails otherwise, so that you can prevent incompatibilities to be introduced in your project.
92
+
91
93
We think Early SemVer gives better flexibility to both library authors and library users since it gives more information about what would be in minor upgrades (we often call this feature release) vs patch. For example, sbt 1 ships bug fixes as 1.3.x patch releases without going through RC cycle, so bug fixes are released quickly.
92
94
93
95
During the minor upgrade (feature release), we aggressively add new features, while maintaining binary compatibility for the plugin ecosystem. These only come out once a year, and it goes through the RC cycle.
@@ -99,25 +101,25 @@ As mentioned earlier, sbt contains a built-in eviction warning feature, but ther
99
101
Since sbt 1.4.0, there is a new setting `versionScheme`, which can be used by library authors
100
102
to declare the versioning scheme they use:
101
103
102
-
~~~scala
104
+
~~~
103
105
ThisBuild / versionScheme := Some("early-semver")
104
106
~~~
105
107
106
108
sbt 1.4.0 includes this information into `pom.xml` and `ivy.xml` as a property. In addition, sbt uses the information to take the guessing out of eviction warning when this information is available.
107
109
108
-
In sbt 1.5.0, eviction warnings will be replaced with [eviction errors][8]. Since it can now reliably detect whether two dependencies with different versions are compatible, or if they conflict, the build will fail if an incompatibility is detected in your dependencies.
110
+
In sbt 1.5.0, eviction warnings will be replaced with [eviction errors][8]. Since it can now reliably detect whether two dependencies with different versions are compatible, or if they conflict, the build will fail if an incompatibility is detected in your dependencies. This is of course possible only if the libraries provide their `versionScheme`, otherwise sbt will keep issuing eviction warnings.
109
111
110
112
It might take a few years for the `versionScheme` information to become prevalent in the ecosystem. In the meantime, as a user of libraries you can manually configure the versioning scheme used by your libraries by using a new setting, `libraryDependencySchemes`. For instance, here is how you can tell sbt that the `circe-core` artifact follows the Early SemVer scheme:
With this setting, the warning caused by the conflicting versions of circe-core
117
119
becomes an error because the version number 0.13.0 is not binary compatible
118
120
with the version number 0.11.1 according to the Early SemVer scheme:
119
121
120
-
~~~text
122
+
~~~
121
123
sbt:killer-app> update
122
124
[error] stack trace is suppressed; run last update for the full output
123
125
[error] (update) found version conflict(s) in library dependencies; some are suspected to be binary incompatible:
@@ -141,7 +143,9 @@ to implement the versioning scheme that you declare in your build, by detecting
141
143
and source incompatibilities introduced between releases.
142
144
143
145
As a library user, starting from sbt 1.5.0 you should configure your
144
-
`libraryDependencySchemes` to get accurate eviction errors.
146
+
`libraryDependencySchemes` to get accurate eviction errors for libraries that don’t (yet) provide their `versionScheme`.
147
+
148
+
_[Eugene Yokota](https://twitter.com/eed3si9n) is the lead developer of sbt. [Julien Richard-Foy](https://twitter.com/julienrf) makes MOOCs at the Scala Center_.
0 commit comments