Clarify release notes about log4cats

[danicheg]

Hehe, we've broken forward compatibility for Scala 2 and 3 in very very different ways. But, yeah, speaking in terms of terminology, looks like you're right.

[danicheg]

So, if we change the release notes to

We've broken forward compatibility for Scala 3 in terms of updating its version from 3.0.x to 3.1.x. So, you'll need to do the same.

Will we be correct as much as we can?

[armanbilge]

Much better. Thank you very much! :)

[danicheg]

but under the strictest definition, it is not source compatible, because it added new public APIs.

I always refer to this definition of source compatibility. And from my way of thinking it fits well.

UPD: Oh darn, I contradict myself here. Users on Scala 3.0.x will get failure at compilation when upgrading the library version without changing Scala 3 version. So source compatibility is broken too. Though, I don't get how to name this sort of compatibility, maybe code-remains-the-same-you-just-need-bump-the-language-version 😆 Some python thing, you know...

Indeed, the release is backwards binary compatible with the entire 2.x series for both Scala 2 and Scala 3.

But users on Scala 3.0.x won't be able to use the new version without upgrading to Scala 3.1.x, isn't it?

[armanbilge]

I always refer to this definition of source compatibility. And from my way of thinking it fits well.

Great, they have a very good definition of source compatibility! For example they say:

For example, adding/removing public class members is a source incompatible change,

So, if you go by this definition, log4cats 2.4.0 broke source-compatibility on both Scala 2 and Scala 3. This is why it's good practice to bump the minor version every time you add any new feature, and use only patch version for bugs that are fixed without changing public API.

---

But users on Scala 3.0.x won't be able to use the new version without upgrading to Scala 3.1.x, isn't it?

You are right about that, but that doesn't mean we broke backwards binary compatibility. When you break backwards binary compatibility, that means user starts to get linking errors in some of their libraries.

Example: I made a mistake in fs2, and it create problems when http4s-jdk-http-client tried to use http4s which had not yet updated to that version of fs2.

• typelevel/fs2#2939

We use MiMa to check binary compatibility, so we can be pretty confident that log4cats 2.4.0 is binary-compatible with every previous 2.x release. In fact, if it's not, we would say it's a mistake, and try and fix it.

[danicheg]

You are right about that, but that doesn't mean we broke backwards binary compatibility.

Honestly, I'm not that binary astronaut, I just want to say we exactly broke some compatibility. Users on Scala 3.0 can't get the upgrade without getting failed compilation.

We use MiMa to check binary compatibility, so we can be pretty confident that log4cats 2.4.0 is binary-compatible with every previous 2.x release.

What about MiMa, I think we have some cheating here. MiMa uses the project's version of Scala (thus 3.1) with the library published for 3.0. And according to Scala 3 documentation, Scala 3.1 should work with libraries published for 3.0. After all, the code on Scala 3.0 doesn't compile with the 3.1 libraries. That's the fact.

[armanbilge]

I just want to say we exactly broke some compatibility. Users on Scala 3.0 can't get the upgrade without getting failed compilation.

I agree with that. I think Ross has a good way of explaining this, see example.

The Scala 3 build now requires at least Scala 3.1.0.

---

MiMa uses the project's version of Scala (thus 3.1) with the library published for 3.0.

Actually, it doesn't. All it does is compare Jar files to each other to look for different bytecode signatures without knowing about Scala versions or anything. Remember how in Mouse you were comparing Scala.js jars to JVM jars and having many problems?

If you load the project in sbt, ++3.1.3 then show core/mimaPreviousArtifacts you will see that it is comparing the Jars of every previous release for Scala 3.

sbt:root> ++3.1.3
[info] Setting Scala version to 3.1.3 on 12 projects.
[info] Reapplying settings...
[info] set scmInfo to https://github.com/typelevel/log4cats
[info] set current project to root (in build file:/workspace/log4cats/)
sbt:root> show coreJVM/tlMimaPreviousVersions
[info] Set(2.1.1, 2.3.0, 2.3.1, 2.3.2, 2.2.0)
sbt:root> show coreJVM/mimaPreviousArtifacts
[info] Set(org.typelevel:log4cats-core:2.3.0 (e:info.apiURL=https://www.javadoc.io/doc/org.typelevel/log4cats-core_3/2.4.0/, e:info.versionScheme=early-semver), org.typelevel:log4cats-core:2.2.0 (e:info.apiURL=https://www.javadoc.io/doc/org.typelevel/log4cats-core_3/2.4.0/, e:info.versionScheme=early-semver), org.typelevel:log4cats-core:2.1.1 (e:info.apiURL=https://www.javadoc.io/doc/org.typelevel/log4cats-core_3/2.4.0/, e:info.versionScheme=early-semver), org.typelevel:log4cats-core:2.3.2 (e:info.apiURL=https://www.javadoc.io/doc/org.typelevel/log4cats-core_3/2.4.0/, e:info.versionScheme=early-semver), org.typelevel:log4cats-core:2.3.1 (e:info.apiURL=https://www.javadoc.io/doc/org.typelevel/log4cats-core_3/2.4.0/, e:info.versionScheme=early-semver))

---

The fact is, if we broke binary-compatibility when we updated to Scala 3.1 in Cats, then we would create major problem for the entire ecosystem. Fortunately, that's not how it's working :)

[danicheg]

Yes, I think the description 'The Scala 3 build now requires at least Scala 3.1.0.' is good. I'm just curious about which one compatibility we broke? :) If it's not binary backward compatibility, then it's forward compatibility? Like Scala 3.1 does.

[armanbilge]

Yes, as soon as you add any new public API to your library you break forward binary compatibility. So actually you broke forward binary compatibility for Scala 2 and 3.

[armanbilge]

Sure, that's fine. I mean you also broke forward-compatibility because you added a new API, and you also broke it on Scala 2, so the Scala 3.1 update is not the only thing involved. But you are right, it is more likely to cause problem than adding an API :)

[armanbilge]

Also, it might be confusing for users who don't know the difference between forwards and backwards compatibility. I think the easiest way to explain it is how Ross does: if you are using Scala 3, you must use Scala 3.1+ as of this release.

[danicheg]

I find this kinda funny when adding any new public function and forcing to change the version of the language are the same type of breaking compatibility.

[danicheg]

Hope we are good now.