Compatibility Considerations

Compatibility refers to the ability of one version of a software component to work in place of another version of the same software component. When "upgrading" versions we refer to "backwards compatibility": can the new version be dropped seamlessly into a working system in place of the older version and the system continue to work properly. This is especially crucial for libraries, like Hibernate.

In an ideal world, this backwards compatibility would be maintained indefinitely. In the real world, as software is developed over time and evolves it is sometimes necessary to change signatures of methods and constructors or to refactor the code in ways (e.g. package changes) that might be disruptive to this backwards compatibility. Here we will discuss the considerations and guidelines followed by the Hibernate team in regards to this.

The first thing to understand is that we conceptually divide the classes of the codebase into 3 broad categorizations: API, SPI, and internal (or private, or implementation, or...). To quickly define these:

• The API is the set of contracts exposed to the application. For example, Session#save. It represents the intended means for the application to interact with Hibernate. Specifically speaking, this is code that we fully expect to be directly linked to (by the compiler) as part of your application bytecode.
• An SPI represents an "integration point" with Hibernate and the contracts needed to perform those integrations.
• The internals are classes and code meant only for Hibernate usage internally.

In terms of compatibility considerations, the SPI categorization is unfortunately too broad. We have been working on defining it in a more granular fashion. A good high level break down (good enough for this discussion anyway) is:

• The contract itself. E.g., the interfaces a "cache provider" would implement to provide caching services as an integration.
• Inputs and outputs defined as part of those SPI contracts.

The other thing that plays into compatibility considerations is the actual "jump" in version we are talking about. Which gets into our versioing philosophy too. We consider the first number the major version. Hibernate ORM has had 4 major versions: 1, 2, 3 and 4. Major versions also have one or more families of releases, which is the second number (4.0 versus 4.1 versus 4.2 e.g.). And then finally we have maintenance releases within those families, which is the 3rd number.