Version 21

    General steps

    This roughly follows the manual release process documented here.

    1. Preparation
    2. Create the tag
    3. Build the release
    4. Build Annotations and Entity Manager manuals
    5. Announce
    6. Upload distributions to SourceForge
    7. Upload documentation to




      1. Set up the next version in JIRA (need Admin privileges for core project):
        Click on menu: Projects - Hibernate Core (HHH)
        On left-side navigation bar, click Versions
        On right side opposite "Versions" title, click Manage Versions
        Rename 3.5.x to the next version, by clicking "Edit details" for 3.5.x and changing the name to the next version (this changes the version for issues resolved for 3.5.x to be for the new version instead)
        Add a new version with Name set to "3.5.x" and Schedule set to the new version.
        Change unresolved issues with the new fix version (e.g., 3.5.3) back to 3.5.x; see warning about issues to be fixed for multiple versions.
        BEWARE: If an issue has the fix version set to multiple versions, then a bulk change of unresolved issues with the new fix version to 3.5.x will drop the other fix versions (e.g a bulk change of unresolved issues with fix version 3.5.3 to 3.5.x will change 3.5.3,3.6 to 3.5.x; 3.6 will be dropped!!!). A safe way is to do a bulk change for each combination of fix versions.  See
      2. Send email to hibernate-dev to request that the fix version for unresolved issues be changed to the new version if they will actually be fixed for that release.
      3. First, make sure you have the absolute latest from SVN.  From the project root, run:
        svn update
      4. Run the tests to make sure everything is kosher.  From the project root, run:
        mvn clean test
      5. Get the changelog (text version) from JIRA and paste it into /changelog.txt with the heading:
        Changes in version [x.y.z] ([]
      6. Commit updated changelog.txt.
      7. Mark version as released in JIRA (adjust release date if necessary).


    Create the tag

    The basic idea here is that you will be committing the project with the [releaseversion] onto HEAD and creating the tag from there.  After remote tagging, you will update HEAD to the [nextsnapshotversion].  You can instead try the attached '' bash script to perform most of this step (after you determine the version); it takes care of all the little details here; all you need to do is determine the release version and next development version and run the script.


      1. Determine the release version "number":
      2. Update the project versions to the [releaseversion]; there are 2 options for this:
        1. Using Perl
          perl -pi -e 's/[currentversion]/[releaseversion]/g' `find . -name pom.xml`
        2. Using xmlstartlet
          for i in `find . -name "pom.xml"`; do xmlstarlet ed -P -N x="" -u "/x:project/x:parent/x:version" -v [releaseversion] -u "/x:project/x:version" -v [releaseversion] $i > tmp; mv tmp $i; done
      3. Commit
      4. Create the tag from the just committed revision (assuming Branch_3_5):
        svn copy [releaseversion]
      5. Update the project versions to the [nextsnapshotversion]; again, there are 2 options for this:
        1. Using Perl
          perl -pi -e 's/[releaseversion]/[nextsnapshotversion]/g' `find . -name pom.xml`
        2. Using xmlstartlet
          for i in `find . -name "pom.xml"`; do xmlstarlet ed -P -N x="" -u "/x:project/x:parent/x:version" -v [nextsnapshotversion] -u "/x:project/x:version" -v [nextsnapshotversion] $i > tmp; mv tmp $i; done
      6. Commit



    Build the release


      1. From a directory where you will do the build, export the tag
        svn export[releaseversion] 
      2. Create a settings.xml for the release. It should set the property jdk16_home, refer to a new local maven repository, get dependencies from An example used for 3.5.2-Final is attached. For more information, see:
      3. Run the build, generating all the artifacts
        mvn -e -X -DtarLongFileMode=gnu --settings /path/to/your/settings.xml clean deploy
      4. Log in to nexus ( ) and close the temporary staging repository. See more details about using the staging repository here.
      5. Test the release in the staging repository.  If there is a problem, drop the staging repo, fix the problem and re-deploy.  If everything is ok, promote the staging repo to the releases repository.
      6. Upload the distribution assemblies to SourceForge (see below)

    Build Annotations and Entity Manager manuals

    Annotations and Entity Manager docs need to be built separately.

    1. To build Annotations manual, cd to annotations and execute: mvn org.jboss.maven.plugins:maven-jdocbook-plugin:2.2.3:resources org.jboss.maven.plugins:maven-jdocbook-plugin:2.2.3:generate -P doc --settings /path/to/your/settings.xml
    2. To build Entity Manager manual, cd to entitymanager and use the same command as used for building the Annotations manual.


    There are a number of places where we should announce the release.  Generally speaking I tend to put all the information in a blog and then reference the blog post in the various communications.

        1. Blog (be sure to use the tags "News", "Core Release" and "Hibernate" for proper RSS feeding)
        2. hibernate-dev mailing list
        3. hibernate-announce mailing list
        4. forum announcement
        5. update #hibernate (on freenode irc network) channel topic



    Upload distributions to SourceForge

    The release distribution bundles need to be uploaded into the SourceForge File Release System (FRS).  There are a number of mechanisms to achieve this.  Generally speaking the Hiberate distributions are too large to work with the UI-approach.  I generally use the SFTP approach.  The SFTP instructions are very good, though I'll include the Hibernate specific here to make things easier:

        1. The connection command for Hibernate would be:
          sftp [username],
        2. The FRS path for Hibernate is /home/frs/project/h/hi/hibernate.  From there it depends on the specific Hibernate project you are dealing with.  For Core, the complete base FRS path would be /home/frs/project/h/hi/hibernate/hibernate3. 
          cd /home/frs/project/h/hi/hibernate/hibernate3
        3. Under there you need to create a directory for the release bundles.  The directory name is used in the UI.  The convention we follow is to name the directory using the [releaseversion].  For an example, assume you are releasing 3.5.0:
          mkdir 3.5.0
        4. Change directory into the one you just created
          cd 3.5.0
        5. Upload the artifacts using the sftp put command
        6. exit sftp