Dealing with Java and Minecraft versions

[falkreon]

Edit: fixed version numbers because I'm a goof and forgot what number we're on

The first major cohort of Jankson users was Minecraft modders. They're still a significant and important part of the user base. But striving for compatibility with Minecraft places restrictions on which Java versions can be used:

• Up to 1.11 requires Java 6
• Minecraft 1.12 - 1.16 requires java 8
• Minecraft 1.17+ requires Java 16

At this point I think it's unlikely that people running Minecraft 1.7.10 are using anything below Java 8, and so Jankson makes use of Java 8 features and uses a Java 8 compatibility level.

Meanwhile, there are newer Java features which would benefit Jankson

• Java 16 would allow us to support record classes
• Java 13 adds text blocks which would allow us to rewrite unit tests in a much more readable way
• Java 11 adds a number of Unsafe features like Variable Handles which can clean up some of the POJO conversion code
• A handful of other improvements along the way, like new String methods and pattern-matching instanceof will make for cleaner and more readable code in the longrun.

We've already been asked for record support. It's only a matter of time before we need to make a call on updating the java version.

In the somewhat-near future, the mainline Jankson branch is going to follow LTS Java. That means a Java 11 version in the near future, and a break in compatibility with anything short of Minecraft 1.17. But I don't want to leave Minecrafters out in the cold, especially since 1.7.10 and 1.12 are such big modded versions.

So the first thing we need to do is consolidate and cleanup the new features as much as they can be in Java 8 - without breaking userspace! - and releasing a final compatibility version. This version will be the start of a new branch, in case we want to make critical fixes or backport new features, but the API and Java version will never change. In terms of versioning, this branch will continue to use "1.x.x" version numbers.

The next thing that will happen is a Java 11 release. This won't have record support, and will go through a number of breaking changes in order to clean up the API and make it more viable long-term. The Jankson Builder will move to some kind of Jankson parameters class that Jankson can be built with directly, and we'll take another look at thread safety and multiple uses. Non-UTF8 Charset support will improve. There's a lot of work to do, and I'm hoping we can stage most of those breaking changes on LTS. We're kind of pushing a tight time table here - Java 17 (the next LTS) might drop while we're still working on the 11 release. Regardless, this release and any bugfix releases on Java 11 will be "2.0.x".

Finally, record support is needed. I've been wanting to do this ever since they announced preview, but it's a steep compatibility cost. At this point, multiline strings in unit tests will also be converted into text blocks. What else this version contains is largely up to the users. I don't know what will happen between now and then, except that users always surprise me and Jankson is always better for listening to them. This version track will require Java 17 and be versioned "2.1.x".

I'm pinning hard versions on these because now, in theory, everyone can write gradle version strings that will pull the newest version they can use, but no newer.

One last thing regarding Minecraft support: Jankson-Fabric (the library mod) will not receive any updates after the Java 8 version. The recommended way to use 2.0.x and 2.1.x Jankson is to shadow and remap. Loom is mature enough to do this, and this takes any mod compatibility concerns (which motivated the existence of Jankson-Fabric) off the table.

[falkreon]

The next (and possibly last) Java 8 release will be 1.2.1. The Gradle version string 1.2.+ should automatically grab the latest artifact on the Java 8 version track.

What needs to be done to release? Well, the annotations need to work. All the time. We've made a lot of progress in other areas, and as long as this one thing works I think we can live with everything else.

What does not need to be done:

• Recursive generics support - part of this will happen in 3.0.x with breaking changes (using Types instead of Classes in many places), and part in 3.1.x
• Fixing comment attribution - Right now comments "belong to" a map entry, and this prevents some kinds of comments from easily or properly re-serializing. For the backend this is a 3.1.x issue at least, but we'll discuss comment API changes in 3.0.x

nothing will change in userspace this release. It should just be a drop-in replacement that works better. We're going to try and squeeze all the breakings in 3.0.