Which version(s) should mimaPreviousArtifacts include?

[SethTisue]

Perhaps we should add some documentation on this.

If I'm publishing version 2.4.6 of my library, do I need to check against 2.4.5 only? Against 2.4.0 only? Against all versions in the 2.4.0–5 range? What about previous minor versions such as 2.3.x?

There is some previous discussion at #483 , but it's just talk on a ticket.

[SethTisue]

On #483, Dale's recommendation was to check against the most recent version only, and we noted that many libraries make bumping that version part of their release process. (We do it that way in scala/scala, for example.)

But that was back in early 2020. Since then, MiMa 0.9.0 introduced support for ignoring package-private methods.

As @armanbilge has noted, e.g. at typelevel/cats#4062 (comment) last year (and also more recently on Discord), this introduces the possibility that a maintainer might, over the course of three releases, change a method as follows:

(version x.0) public -> (version x.1) package private -> (version x.2) removed

Each of the two steps individually passes MiMa, but taken together they break bincompat.

[julienrf]

How about a compromise solution where we keep MiMa's ability to allow the public-to-private[pkg] change, but make it opt-in rather than default behavior?

I think requiring the addition of a MiMa exclusion is equivalent to an opt-in solution, no?

[armanbilge]

I don't think it is. Once you add the MiMa exclusion, nobody is watching your back anymore.

The current situation, where public-to-private[pkg] are allowed, is safe so long as you keep checking against all previous artifacts.

[SethTisue]

I think requiring the addition of a MiMa exclusion is equivalent to an opt-in solution, no?

See @armanbilge's previous remarks about the disadvantages of maintaining filter lists. The hassle involved is annoying, and there is a real risk of existing filters accidentally masking new binary incompatibilities.

[julienrf]

Then, as Sébastien suggested, it should be a switch to either reject public to private[pkg] (and perform no checks on private[pkg] members), or reject binary incompatibilities in private[pkg] members (and accept changing the visibility of a member from public to private[pkg]).

[armanbilge]

You are solving for the case where you only want to check bincompat against the last release. Unfortunately, this will create lots and lots of new MiMa issues for existing projects that use those changes and rely on comparing bincompat against all previous versions.

[SethTisue]

Any recommendation we make here could also potentially be propagated to downstream tooling such as https://github.com/scalacenter/sbt-version-policy and https://github.com/typelevel/sbt-typelevel. At present, sbt-version-policy compares against only a single previous version. sbt-typelevel compares against a range (previousReleases, plural).

cc @julienrf @sjrd

[dwijnand]

In retrospect, MiMa is fast enough that I don't think running against multiple versions is so silly - obviously given the Arman's example.

[zarthross]

sbt-version-scheme-enforcer Is another exploration of that idea, that does a pretty good job of adding exceptions based on the version scheme and the new version number.

[armanbilge]

Thanks, wasn't aware of that one too! If I am reading it correctly it appears to have the same issue of only comparing to one previous artifact, instead of all of them. cc @isomarcte

https://github.com/isomarcte/sbt-version-scheme-enforcer/blob/2773c5375bec194f5c2ab0f0c49bfe6012e041cd/plugin/src/main/scala/io/isomarcte/sbt/version/scheme/enforcer/plugin/SbtVersionSchemeEnforcerPlugin.scala#L152-L166

[zarthross]

I was under the impression that it would do multiple versions:

From the readme versionSchemeEnforcerInitialVersion

The initial version which should have the versionScheme enforced. If this is set then verions <= to this version will have Mima configured to not validate any binary compatibility constraints. This is particularly useful when you are adding a new module to an exsiting project.

[armanbilge]

It think it just uses that to determine what's the earliest version of a module that exists (so if you are on or prior to that version to not attempt to check artifacts).

Of course, I could be reading the wrong part of the code, but the part I linked is making a singleton Set.

[zarthross]

No, your right... that does look like a singleton set... that's too bad. Maybe @isomarcte has some thoughts.

[armanbilge]

Somewhat off-topic for this particular discussion, but it seems to me that part of the problem is that we don't have enough knobs for controlling binary-compatibility independently of source-compatibility. Thus, the two concepts get conflated.

For example, the point of the package-private trick is to remove a public API (a source-level concern) without removing a public ABI (a binary-level concern).

If we lose the ability to remove public APIs without triggering MiMa, then ultimately users will have to pay a price for this. Maybe that price is negligible with the proper use of @deprecated annotations and IDEs that respect them. I don't know.

Scala 3 has already made a fantastic step in this direction with the @targetName annotation, which was an essential tool for solving typelevel/cats#4062.

Towards that, I think having an annotation to mark a package-private as public ABI would be fantastic. I can already think of two use-cases:

1. Hiding deprecated public APIs, that have source-compatible replacements.
2. Multi-repo projects such as http4s and Akka frequently have "public-internal" APIs. They are package-private, because they are not meant for public consumption, only internal use. But because they may be used across compilation/versioning boundaries, they form an important part of the public ABI. Currently there is no way to express this and get binary-compatibility support from MiMa.

[zarthross]

I believe circe was recently bitten by something like # 2 here... without Mima reporting bin-compat issues around package-private methods we ended up releasing something that was not binary compatible in Scala 3 by accident. See circe/circe#2089. The fix is easy, but I wish I could have opted into this behavior of mima rather than it being the default.

[armanbilge]

It might be happening!! See:

• SIP-52 - Binary APIs scala/improvement-proposals#58