Document version compatibility goals

[ceedubs]

I think that we should document what our goals are with respect to binary/source compatibility as we reach 1.0.

I'd be inclined to propose the following:

• A change to only the patch version will always be binary compatible. For example 1.0.2 is binary compatible with 1.0.0 and 1.0.1.
• A change to the minor version number may not be binary or source compatible. For example, 1.1.0 is not necessarily binary compatible with 1.0.0.
• For incompatible changes introduced in a new version, we will try to make the transition as painless as possible. Before methods or types are removed, they will go through a deprecation cycle. If a change may silently lead to different behavior, we will try to highlight it in the release notes.
• The cats-kernel module will remain binary-compatible across minor versions. Binary-incompatible changes to this module should only occur alongside a major version bump (which will be few and far-between).
• We plan to support minor versions for at least ...some amount of time. Personally I'd be inclined to try to support minor versions for the greater of (2 years after their release, 1 year after the release of the next minor version). By support I mean backporting and publishing bugfixes and significant performance improvements.

What do people think about the ones I have? Are there others that we should add?

One thing that I don't really know how to quantify is source-compatibility. In general I want us to strive for source-compatible changes, but as long as they aren't too intrusive, I think it's less of a concern than binary compatibility.

cc @johnynek and @mpilquist who I think are both interested in compatibility.

[kailuowang]

Just my 2 cents.
Shall we also include in the vision that we should try to maintain binary comp between minor versions also as much as possible? Or maybe be specific about a certain target minor release's binary compatibility goal on a case by case basis?
As such a foundational library, binary comp is really important, I am not sure a guarantee of only patch version binary comp is strong enough. I mean if we only give that guarantee, then either the users are stuck with a minor version or the contributors are (can only release new features (binary compatible) in patch releases.

[johnynek]

In my view, version numbers are cheap but compatibility promises are valuable. I would go for something closer to semantic versioning:

After 1.0.0, changes mean:
patch level change: zero API or semantic change, only method local changes for bug fix or performance fix.
minor level change: any API addition that is source and binary compatible (at least binary compatible because we have a tool to check that).
major level change: any change that fails MIMA for the previous version.

Usually, you can avoid breaking binary compatibility by making some slightly different choices and since we hope for wide adoption, each binary break is a huge downstream cost we often don't see. Especially as cats is adopted by other libraries, so that it is often a diamond dependency. I'm a huge advocate of making some compromises to keep binary compatibility.

I think this comes down to goals: my goal is adoption and impact (there are other goals, such as demonstration, teaching, etc...). With adoption means people will want to use N libraries, they will all want slightly different cats, and so most build tools will give them the largest version number. We should work very hard to make that almost always compatible.

[ceedubs]

@johnynek are there examples of other prominent libraries in the scala ecosystem using that sort of versioning scheme? Out of all of the libraries that I've had to worry about version compatibilities in recent years (scalaz, shapeless, akka, scodec, scala itself), minor versions track binary incompatibilities and major versions track significant changes to the library (rewrites, major overhauls, etc). I don't have any super strong opinions on versioning, but I also don't want to go against the grain and confuse users.

[kailuowang]

related to #608

[kailuowang]

There are two popular versioning schemes here:

• the java/scala style of epoch.major.minor (proposed by @ceedubs in this thread)

• semantic versioning of major.minor.patch. (proposed by @johnynek )

Both only breaks bin compat at major versions. IMO, it's basically a trade-off between the ability to release epoch or patch, neither is very frequent to us, maybe patch is a little bit more relevant.

Most other scala libraries I know are using the java/scala style. But Akka changed the versioning scheme to semantic versioning since 2.4 possiblly because that like cats, it sits near the bottom of the dependency chain and takes bin compat as a high priority.

I am not sure if one is strictly more suitable to cats than the other. I propose we just hold a vote and move forward with the decision.

[fommil]

semver

[alexandru]

When talking of epoch.major.minor, the distinction between epoch and major is arbitrary.

How many changes does it take for us to consider that an epoch happened?
Is 10 functions or classes changed / removed enough? How about 100?

My problem with epoch.major.minor is that it is lying, being preferred because we get too attached to version numbers and because we don't really want to tell users that their software will break. Well, in regards to binary compatibility, whether you have a single change, or 100, it doesn't matter that much, because in both situations the user gets screwed if not careful.

So I vote for "semver". It's awful, but it's the standard way to communicate breakage.

[tpolecat]

I lean toward @johnynek's proposal because it makes use of the full namespace and is defined in a way that could be automated, at least in principle. It makes it harder to indicate rewrite-scale breakages but these are so infrequent in practice we can indicate them in some other way, like jumping up the next round 100 or something.

[eed3si9n]

Semantic™ or otherwise, version number is a String that eventually gets selected by dependency resolution engines like Ivy and Maven. Their algorithms will not respect whether the graph brings in 0.9.0, 1.x, or 2.x.

A third option you might want to consider is using organization (or groupId in Maven) and the package name for major versioning. For instance:

• Cats 1.0 uses org.typelevel.cats as the organization, and cats as the package name.
• Cats 2.0 uses org.typelevel.cats2 and cats2.

This allows cats.Functor to be binary compatible forever (up to scalaVersion), and safely allow Cats 1.x and Cats 2.x to co-exist in a large system.