JSTEP 1

JSTEP-1: Major Version 3.x Upgrade Compatibility Details

Note: matching github issue: #35

Background

Jackson follows Semantic Versioning, and as such Major Version change planned from 2.x to 3.0 indicates major, backwards-incompatible changes. Such changes are made in order to improve Jackson in ways to would not otherwise be possible, including (but not limited to) things like:

• Removal of deprecated methods in public API (note: Jackson minor versions allow more aggressive removal of internal methods)
• Changes to required abstract methods (for abstract classes and interfaces)
• Renaming of public API classes
• Changes to default settings, behavior

Prior art

Jackson has already undergone one major version upgrade: from 1.9 to 2.0. We consider that upgrade largely successful and positive, due to changes taken to avoid class-loading collisions across 1.x and 2.x, which essentially allow 1.x and 2.x implementations to co-exist within same JVM. There are of course downsides -- there is no perfect way to upgrade; and it could be argued that need to do major upgrade is a sign of fundamental problems with upgrade -- main complaint being that upgrade process even for simplest cases is more involved than just upgraded dependency version number.

What was done with 1.9-to-2.0 upgrade was essentially

1. Move root Java package from org.codehaus.jackson to com.fasterxml.jackson, to avoid class collisions
2. Change Maven group id from org.codehaus.jackson to com.fasterxml.jackson[.core]
   • Some maven artifact ids were also changed (like jackson-mapper-asl to jackson-databind), but that was optional cleanup; change of group id would have sufficed for isolation.

Potential avoidable problems

Although upgrade from Jackson 1 to Jackson 2 seemed to go largely well for most users (when they chose to do that), one somewhat painful and potentially unnecessary part was handling of annotations. Since annotations are more of metadata, and since changes between 1.9 and 2.0 were minimal, it was possible to create value classes (POJOs with no Jackson dependency exception for annotations) that worked with both Jackson 1.x and 2.x -- but if any annotations were required, both 1.x and 2.x annotations were needed as neither could read "other" annotations (note: it is actually possible to implement Jackson AnnotationIntrospector that DOES understand both -- and such implementations were written by 3rd party developers). But it seems that it might have been possible to handle annotation package compatibility different from other packages: we will extend on this in sections below, suggesting another way to tackle version evolution for annotations.

High-level Proposal

We should follow footsteps of Jackson-1-to-Jackson-2 upgrade in most parts, renaming Maven group-id (and possibly some of artifact ids) as well as Java packages.

But one exception is that we should consider keeping jackson-annotations compatible across major versions. This would require keeping same Maven group and artifact ids, as well as Java package name. There are some trade-offs -- essentially, difference in versioning may seem confusing to users -- but there is some value in ability to use only a single set of annotations on (non-Jackson) POJOs, regardless of whether Jackson 2.x or 3.x is actually used for processing.

Proposal details

General naming

There is one general naming question to decide first. Should we make:

1. Minimal name change, like "com.fasterxml.jackson" -> "com.fasterxml.jackson3", OR
2. Bigger name change, like "com.fasterxml.jackson" -> "org.jackson" (or something)

If we wanted to do latter, we'd have to come up with a new

Maven coordinates

Java packages