# Java Interoperability Policy for Major Version Updates

DevFeed: [Java Interoperability Policy for Major Version Updates](<https://devfeed.tech/articles/java-interoperability-policy-for-major-version-updates-20943.md>)

Original publisher: [Read original article](<https://jakewharton.com/java-interoperability-policy-for-major-version-updates/>)

Published: 2015-12-11T00:00:00Z

Content type: article

Language: en

Sources: [Jake Wharton](<https://devfeed.tech/sources/jake-wharton.md>)

Topics: [Java](<https://devfeed.tech/topics/java.md>), [Library](<https://devfeed.tech/topics/library.md>), [interoperability](<https://devfeed.tech/topics/interoperability.md>), [API](<https://devfeed.tech/topics/api.md>), [Maven](<https://devfeed.tech/topics/maven.md>)

Tags: [api](<https://devfeed.tech/tags/api.md>), [compatibility](<https://devfeed.tech/tags/compatibility.md>), [dependencies](<https://devfeed.tech/tags/dependencies.md>), [interoperability](<https://devfeed.tech/tags/interoperability.md>), [java](<https://devfeed.tech/tags/java.md>), [libraries](<https://devfeed.tech/tags/libraries.md>), [maven-central](<https://devfeed.tech/tags/maven-central.md>), [modules](<https://devfeed.tech/tags/modules.md>), [upgrade](<https://devfeed.tech/tags/upgrade.md>)

## AI overview

This article proposes a Java interoperability policy for major version updates of foundational libraries. It recommends versioned Java packages, optional compatibility shims in sibling artifacts, and library names in Maven group IDs to reduce conflicts from transitive dependencies and support gradual upgrades.

## Source excerpt

Major version updates to libraries solve the API warts of old and bring shiny new APIs to address previous shortcomings--often in a breaking fashion. Updating an Android or Java app is usually a day or two affair before you reap the benefits. Problems arise, however, when other libraries you depend on have transitive dependencies on older versions of the updated library. Retrofit 2.0 is nearing release and it comes with three years of knowledge gained since its version 1.0--some of which is in backwards-incompatible API changes. We are fortunate to say that Retrofit has become a popular library, but it presents a real problem in that other libraries have been published which rely on its 1.x API. While a sudden breaking change doesn't present an immediate problem for them, consumers of those libraries wanting to upgrade their apps to the new API face a difficult choice. This problem is not new, and I won't waste time rehashing all its nuances. After some discussion with Jesse Wilson, we have decided on a course of action for the libraries we manage going forward in order to mitigate this pain. The following does not assume strict semantic versioning, but general adherence to its idea of major version bumps. For major version updates in significantly foundational libraries we will take the following steps: Rename the Java package to include the version number. This immediately solves the API compatibility problem from transitive dependencies on multiple versions. Classes from each can be loaded on the same classpath without interacting negatively. Users can perform major versions updates gradually or in increments rather than requiring an immediate switch. If possible, shims for older versions can be built on newer versions in a sibling artifact. For example, versions 0.x and 1.x would be under com.example.retrofit, versions 2.x would be under com.example.retrofit2, and so on. (Libraries with a major version of 0 or 1 can skip this, and only start with major version 2 a