Huge Project, Small Team
Hibernate is a huge Open Source project (multiple projects, really). And yet its core development team is amazingly small. Which means that we need to pick our battles...
One of the biggest low-hanging fruits for us in this regard is to maintain just the most recent release(s). It is just not practical for us to support more than 1 or 2 branches simultaneously.
What does "support" mean? It defines:
- the branches/releases we maintain in terms of accepting pull requests and back-porting changes
- the versions against which we consider bug reports as valid
This support is defined primarily by version. We generally follow Semantic Versioning; however, there are minor nuances within this that are important to understand.
While we do not explicitly support OSGi, we do also follow OSGi version naming which means that Hibernate versions are always made up of 4 components - {major}.{minor}.{micro}.{qualifier}.
For Hibernate, this all implies the following versioning semantics:
-
{major}indicates a "significant" change. The implications range from changes to external contracts to removal of deprecated stuff to new features. New major versions will be backwards incompatible to some degree. -
{minor}indicates new feature(s) which are not disruptive to applications in terms of backwards compatibility - for sure at the API level; we strive to maintain compatibility at the SPI (integration) level, though sometimes these do change when absolutely necessary. -
{micro}indicates a bug fix release and includes only, oddly enough, bug fixes -
{qualifier}denotes the status of a release as "stable" versus "in development":- development releases include:
-
AlphaandBetawhich follow the standard semantic -
CR(Candidate Release) instead of the more generally usedRC(release candidate)
-
- stable releases always use
Final
- development releases include:
For the {qualifier} terms, these were chosen for sortability. OSGi defines no set of values here, so strictly according to OSGi they are simply sorted alphabetically. These terms Hibernate uses give us the "natural" Alpha -> Beta -> CR -> Final sequence.
There are cases which are exceptions to this version-based focus of support.
Starting with 6.0, I have started to more formally publish these. See e.g.:
- https://docs.jboss.org/hibernate/orm/6.0/incubating/incubating.txt
- https://docs.jboss.org/hibernate/orm/6.0/internals/internal.txt
Hibernate identifies certain contracts as "incubating" which is a fancy, formalized way of documenting things which have different backwards compatibility expectations. These are contracts which were recently added which we believe may need to change in the future for various reasons. In the code, things which are incubating are identified via @Incubating.
Things we do not intend for applications nor integrations to use. These are strictly for Hibernate use. We do not fix "bugs" if those bugs only occur in the way an application/integration may try to use them. These are indicated by contracts in packages named **.internal.** as well as via @Internal.
The transition from "supported" to "not supported" is based on subsequent releases. This is easiest to understand through examples.
Say we have version 1.0 which is currently supported. We start work on version 1.1. We continue to support 1.0 while 1.1 is going through Alpha and Beta and CR. We will continue to release 1.0 bug-fix releases during this time period.
Once 1.1 "goes Final", we no longer support 1.0 and we will no longer do any further 1.0 releases. 1.1 is backwards compatible and is (should be) a drop-in replacement.
1.1 is now the supported version. We start work on 2.0. We again continue to support 1.1 while 2.0 is going through Alpha and Beta and CR.
After 2.0 "goes Final" we will continue to support 1.1 and do bug-fix releases for "some period of time". "Some period of time" is, granted, a bit vague but there are simply too many variables that go into this to give a hard-and-fast amount of time. We temporarily continue to support 1.1 because we know this is likely not a simple drop-in replacement for some users. This continued support allows a transition period.