Hibernate has moved to Git (hosted on GitHub) for source control. That has been well documented. I wanted describe the approach Hibernate takes to branching, versioning and releasing as it is something that has come up a number of times, even prior to the move to Git.


For versioning, Hibernate follows the OSGi guidelines that are well described here. Here is how we view the components that make up an OSGi version:

  • major - To Hibernate, this denotes major, disruptive changes. Think back to Hibernate2 and the migration to Hibernate3 and that is the type of disruption I am talking about. The move from 3.x to 4.x will be less disruptive in that sense, but there is still a significant change.
  • minor - We sometimes refer to this as a series so that you might hear Hibernate developers talk about the 3.5 series or 3.6 series. Within a series Hibernate strives for API stability. A change in this component (3.5 to 3.6) denotes some API change, though its usually an addition and therefore less disruptive than discussed above.
  • micro - For Hibernate these denote bugfix releases.
  • qualifier - Hibernate uses this component really only for pre-final releases (alphas, betas, etc). Once we get to Final (x.y.0.Final) we begin to increment the micro but continue to use the Final qualifier (x.y.1.Final) for release sorting (and therefore ranging) purposes.

Maintenance Branches

Hibernate maintains branches for each (major.minor) series. During the move to GitHub we took the opportunity to drop off the very old branches. So currently there are bugfix branches for 3.2, 3.3, 3.5 and 3.6 (currently the master branch is ongoing 4.0 work). We branch off the series to make it possible to port fixes back to them. As an example... Currently the active maintenance branch is 3.6; master is the ongoing work for 4.0. 4.0 has lots of disruptive changes as discussed above (though the same discussion holds true for series changes due to API differences). Having the 2 branches allows us to work both code-bases simultaneously. We can fix a bug and apply that change to both the 4.0 and 3.6 code-bases; yet 4.0 can evolve independently like it needs to. On master Hibernate has moved to Gradle for its build tool and at the same time I decided to move to a more standard module directory naming scheme; unfortunately that causes some interesting challenges in trying to backport fixes which I'll discuss in a separate blog.

Maintenance Releases

Hibernate performs maintenance releases from the active maintenance branch. Currently, that means we will do maintenance releases from the 3.6 branch. We will continue to do that until 4.0 becomes Final at which point we will stop 3.6 maintenance, make 4.0 the active maintenance branch and move master to 4.1 development. This is the general outline we follow. If you look back, for example, to 3.6 development you can see that illustrated. We kept doing 3.5 maintenance releases up until the time 3.6 went Final.

Time Boxing

The Hibernate team loosely follows a time boxing schedule for releases. Personally I don't believe in rigidity here, especially for maintenance releases. We have become very good at sticking to time boxing for Alpha, Beta and CR releases which is where I see the benefit the most. We have opted for a 2-week time box for Beta and CR releases, which has worked out really really well for us in my opinion. We have done both 2- and 4-week boxes for Alphas; we will continue to fine tune that (like I think 4.0 dev will use 4-week boxes just because there is so much change going on).

1 comment:
23. Nov 2010, 10:41 CET | Link


you might be interested by a small Java library I created to help applying semver principles ( to your project. It also includes a maven plugin to check for backward compatibility during maven lifecycle. See (maven site


Post Comment