Version 3

    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 docs.jboss.org

     

    Preparation

     

      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.6.x to the next version, by clicking "Edit details" for 3.6.x and changing the name to the next version (this changes the version for issues resolved for 3.6.x to be for the new version instead)
        Add a new version with Name set to "3.6.x" and Schedule set to the new version.
        Change unresolved issues with the new fix version (e.g., 3.6.3) back to 3.6.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 http://jira.atlassian.com/browse/JRA-21828
      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 git.  From the 3.6 branch, run:
        git pull
        
      4. Run the tests to make sure everything is kosher.  From the project root, run:
        mvn clean test
        
      5. Check for any issues that have been resolved for this release with resolution other than 'Fixed'. If there are any, then remove the fix version from those issues. This avoids erroneously including them in the release notes.
      6. Get the changelog (text version) from JIRA and paste it into /changelog.txt with the heading:
        Changes in version [x.y.z] ([yyyy.mm.dd]
        
      7. Commit updated changelog.txt and "git push".
      8. 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 'tagRelease.sh' 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": http://community.jboss.org/wiki/JBossProjectVersioning
      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="http://maven.apache.org/POM/4.0.0" -u "/x:project/x:parent/x:version" -v [releaseversion] -u "/x:project/x:version" -v [releaseversion] $i > tmp; mv tmp $i; done
          
      3. Commit and push
      4. Create the tag from the just committed revision:
        git tag -a [releaseversion] -m 'Create tag for [releaseversion]'
        
      5. Explicitly push the tag:
        git push origin [releaseversion]
        
      6. 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="http://maven.apache.org/POM/4.0.0" -u "/x:project/x:parent/x:version" -v [nextsnapshotversion] -u "/x:project/x:version" -v [nextsnapshotversion] $i > tmp; mv tmp $i; done
          
      7. Commit and push.

     

     

    Build the release

     

      1. From a directory where you prepared the release, create an archive from the release tag:
        git archive --format=tar --prefix=hibernate-core-[releaseversion]/ [releaseversion] | (cd .. && tar xf -)
        For example, for 3.6.2: git archive --format=tar --prefix=hibernate-core-3.6.2-Final/ 3.6.2.Final | (cd .. && tar xf -)
      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 https://repository.jboss.org/nexus/. An example used for 3.5.2-Final is attached. For more information, see:
        1. http://community.jboss.org/wiki/MavenGettingStarted-Developers
        2. http://community.jboss.org/wiki/MavenSettingsExample-Developers
        3. http://community.jboss.org/wiki/Mavensettingsxmlmaskingpassword
      3. Change directory to the untarred archive.
      4. Run the build, generating all the artifacts
        mvn -e -X -DtarLongFileMode=gnu --strict-checksums --settings /path/to/your/settings.xml clean deploy
      5. Log in to nexus ( https://repository.jboss.org/nexus ) and close the temporary staging repository. See more details about using the staging repository here.
      6. 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.
      7. Upload the distribution assemblies to SourceForge (see below)

    Build Entity Manager docs

    Entity Manager docs need to be built separately:

    cd entitymanager
    mkdir src/main/docbook/en/images #plugin expects this directory
    mvn org.jboss.maven.plugins:maven-jdocbook-plugin:2.3.4:resources org.jboss.maven.plugins:maven-jdocbook-plugin:2.3.4:generate -P doc --settings /path/to/your/settings.xml
    

    Announce

    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],hibernate@frs.sourceforge.net
          
        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