RichFaces 4.x Release Procedure

Version 49

    The document was converted to AsciiDoc and moved to the source code repositories:

     

     

    Deprecated

     

     

     

    This document covers the steps and requirements for releasing any version RichFaces 4.0 including the core project, documentation, and supporting modules.

    Prerequisites

    Before beginning any of the procedures below you need to setup your maven installation.

     

    It is recommended to use special settings.xml for release process.

    Using referenced settings.xml you can use separated local repository which will be popullated only with artifacts from JBoss Staging repository.

     

    Further informations can be found in JBoss.org developer settings instructions:

     

    The richfaces project already uses jboss-parent as its parent, so it inherits distrubutionManagement.  Pay particular attention that you have the JBoss repository authentication settings configured.

     

    You also need to make sure you have access to the JBoss nexus server, with permissions to stage, and release.  The documents above have information on this, but if you are not sure please contact JBoss helpdesk, and follow up with the project lead.

     

    Be sure to use Maven 3.0.4 and Oracle JDK 1.6.0_33.

     

    (Note: with JDK 1.6 you will likely need to setup MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=512m")

     

    Also the person performing any of the releases below should also post a message to the RichFaces developer forum stating:

    The release process for <4.1.0.M1> is about to begin. Further commits into develop branch will not be considered in release.

    When the release is completed be sure to post to the forums again.

     

    Review Issue Tracker Status and Continuous Integration

     

    Before starting any release steps, make sure the CI tests pass and that all issues scheduled to particular version are resolved.

     

    Finish Release Notes

     

    build/dist/release-notes.txt should be updated before starting with release

    Tagging Core Framework Modules

    • Be sure that any updates/releases to supporting modules (below) have been released if required.
    • Follow the JBoss milestone/CR/Final naming convention outlined here: JBossProjectVersioning

     

    Note: in following instructions, angle brackets are used as placeholders and states sample values. Be sure to replace them with correct values including the angle brackets.

     

    Branch & Tag Naming

     

     

    DescriptionRelease Development OriginRelease Development BranchDevelopment POM versionRelease Branch
    Release POM version
    TagNext POM version
    Milestone 1developdevelop4.1.0-SNAPSHOTrelease/4.1.0.M14.1.0.20110805-M14.1.0.20110805-M14.1.0-SNAPSHOT
    Release Candidatedevelopdevelop4.1.0-SNAPSHOTrelease/4.1.0.CR14.1.0.CR14.1.0.20111111-CR14.1.0-SNAPSHOT
    Final (Minor) Releasedevelopdevelop4.1.0-SNAPSHOTrelease/4.1.0.Final4.1.0.Final4.1.0.20111212-Final4.2.0-SNAPSHOT
    Micro Release (Candidate)tag: 4.1.0.20111212-Finalrelease-develop/4.1.14.1.1-SNAPSHOTrelease/4.1.1.CR14.1.1.CR14.1.1.20120101-CR1-
    Hotfixtag: 4.1.1.20120124-Finalhotfix/4.1.1.Final_RFPL-12344.1.1-SNAPSHOTrelease/4.1.1.Final_RFPL-12344.1.1.Final_RFPL-12344.1.1.20120203-Final_RFPL-1234-

     

    For more information on workflow: https://community.jboss.org/wiki/RichFacesGitWorkflowModel

     

     

    Procedure

     

    1. Checkout core project modules
      • $ git clone git@github.com:richfaces/build.git
        $ bash build/scripts/richgit.sh

    2. (optional: diverge a Release Development Branch from Release Development Origin - optional when they equals)
      •  

        $ bash build/scripts/richgit.sh -e git checkout <release_development_origin> -b <release_development_branch>

         

    3. (optional: do an preparation for divering Release Branch (e.g. cherry-picking commits to be included in Micro Release or Hotfix))
      • $ cd components/
        $ git cherry-pick <commit_id_1>
        $ git cherry-pick <commit_id_2>
    4. diverge a release branch
      • $ bash build/scripts/richgit.sh -e git checkout <release_development_branch> -b <release_branch>

    5. Bump to timestamped release versions <4.1.0.20110805-M1>
      •  

        $ bash build/scripts/change_version.sh -r -o <development_pom_version> -n <release_pom_version>
        $ bash build/scripts/richgit.sh -e git add -A
        $ bash build/scripts/richgit.sh -e "git commit -m 'changing version to <release_pom_version>'"

         

    6. In next steps, be sure to point maven to local copy of release settings.xml and to activate profiles build and release in each step
    7. Run dry run to verify build with release versions
      • $ cd build/
        $ mvn -s <settings.xml> -P build,release clean verify
      • If there are problems with build ( failed tests, SNAPSHOT dependencies, etc...) communicate with development team, and resolve.
    8. Push Tag to the repository
      • $ bash build/scripts/richgit.sh -e 'git tag -a <tag> -m "Tagging release <tag>"'

        $ bash build/scripts/richgit.sh -e git push origin <tag>

      • (when building Hotfix, the origin you are pushing to can be your own repository - the branches and tags can be easily merged into upstream repository later - it means you also can't break anything in upstream repository)
    9. Publish Release Branch to repository
      • $ bash build/scripts/richgit.sh -e git push origin <release_branch>
    10. Bump the develop branch version and push it (if necessary = only for Final releases)
      • $ bash build/scripts/richgit.sh -e git checkout develop
        $ bash build/scripts/change_version.sh -r -o <4.1.0-SNAPSHOT> -n <4.2.0-SNAPSHOT>
        $ bash build/scripts/richgit.sh -e git add -A
        $ bash build/scripts/richgit.sh -e 'git commit -m "bumping version to 4.1.1-SNAPSHOT"'
        $ bash build/scripts/richgit.sh -e git push origin develop:develop
        
        $ bash build/scripts/richgit.sh -e git checkout release/4.1.0.Final
        


    Staging

    1. Now you can perform the actual release build from the tag, and deploy using
      (you can use install instead of deploy in case you want just build release locally)
      1. $ mvn -s <settings.xml> -P build,release clean deploy

     

    • This will build from the tag, and perform the actual uploads to the JBoss staging repo.
      • If there is authentication problems contact project lead
      • If there are errors uploading for some reason you need to "drop" what ever was staged following: Maven Deploying a Release
        • Then attempt the build again.  If the problems continue contact project lead
    • Next you need to "close" the stage following the Maven Deploying a Release with the comment "RichFaces <rel-ver> Stage"

     

    The release is now staged, and the release jira should be updated with links to the public stage, and the private stage URL.  See the Milestone 3 release jira for an example.

     

    Releasing/Dropping

    Once QE and development have verified and cleared the staged release following the <link> jira process the next step is to promote the staged bits to JBoss maven release repo.

     

    This is very easy.  Simply log into the nexus server following Maven Deploying a Release and "promote" the release.  Use the following release comment: "RichFaces <rel-ver> Release".

     

    If QE and development fine issues, and the release needs to be dropped follow the directions above, and "drop" the stage.

     

    Merging Release branch with Develop branch

    One more step is required to finish the release process - publish release branches on GitHub.

    It is recommended to do following process for each framework repository separately since there may occur merge conflicts.

     

    1. update the develop and master branches (in order to merge to latest state)
      $ bash build/scripts/richgit.sh -e git fetch origin
      $ bash build/scripts/richgit.sh -e git checkout develop
      $ bash build/scripts/richgit.sh -e git rebase origin/develop
      $ bash build/scripts/richgit.sh -e git checkout master
      $ bash build/scripts/richgit.sh -e git rebase origin/master
    2. for each module {archetype-simpleapp, build, core, components, dev-examples, showcase}
      • merge release branch to develop and to master
        • note: the merging into the master is done only for Final releases, since it should contain only stable bits (4.2.0.Final, 4.2.1.Final, 4.3.0.Final; no 4.2.1.CR1 or 4.3.0.M1)
        • using git-flow
          • $ git flow release finish <4.1.0.M1>
            # resolve merge conflicts
            $ git tag -d 4.1.0.M1 # remove automatically created non-timestamped tag
            
            
        • without git-flow
          • $ git checkout develop
            $ git merge --no-ff <release/4.1.0.M1>
            # resolve merge conflicts
            $ git checkout master
            $ git merge --no-ff <release/4.1.0.M1>
            # resolve merge conflicts
            $ git branch -d <release/4.1.0.M1>
    3. bump versions on release branch to new development version (don't forget to increase minor version in Final release (4.1.0 becomes 4.2.0), do not increase it in releases before Final) - warning: new version needs to correspond with current develop version
      • $ bash build/scripts/change_version.sh -r -o <4.1.0.20110805-M1> -n <4.1.0-SNAPSHOT>
        $ bash build/scripts/richgit.sh -e git add -A
        $ bash build/scripts/richgit.sh -e "git commit -m 'changing versions back to development: <4.1.0-SNAPSHOT>'"
    4. try the snapshot build
      • $ cd build/
        $ mvn clean verify -Pbuild
        
    5. publish merged branches
      • warning: be sure to do not push changes in master when this is not Final release! (see note in step (2))
      • $ bash build/scripts/richgit.sh -e git push origin develop:develop
        $ bash build/scripts/richgit.sh -e git push origin master:master
        
    6. remove the remote release branch
      $ bash build/scripts/richgit.sh -e git push origin :release/<4.1.0.M1>

     

    Notes

     

    Note: when solving merge conflicts, you need to go through conflicts, fix them and commit, following commands may be helpful:

    • # merge using graphical tools according to your preferences
      $ git mergetool
      # commit changes after merging
      $ git commit -m "merging 'release/4.1.0.M1' into master (or develop)"

    Note: there will be probably lot of merge conflicts with master branch. Since the master branch needs to be equal to the contents of the tag, you can do the following trick after the merge for solve conflicts, it will apply the difference between master:

    • $ git diff 4.1.0.20110805-M1 | git apply -R -
      $ git add -A
      $ git commit -m "merging 'release/4.1.0.M1' into master"

     

     

    Supporting Modules

    These supporting modules live outside of the standard project, and should be updated/released rarely.  They also follow their own version scheme of integers ( 1,2,3,etc...)

    1. Appropriate parent.version/dependency.version references to them in the project should be updated.

     

    It is important when releasing the richfaces-parent to make sure references to it are also updated in the core project modules as appropriate.

     

    The process is similar to framework modules, except that each support module is located in one repository.

    After staging support modules to staging repository, bump their version across core framework and then verify the build against staging repository.

     

    parent

    checkstyle

    shade-transformers

    vdl-doc

     

     

    Documentation

     

    1. Clone docs repository (writable SSH access): https://github.com/richfaces/docs
    2. enter docs repository
    3. ../build/scripts/change_version.sh -r -o {current_development_version} -n {release_version}
      (e.g. 4.2.0-SNAPSHOT -> 4.2.1.Final)
    4. git add -A
      git commit -m "changing to release version: {release_version}
      (e.g. 4.2.1.Final)
    5. git tag {tag}
      (e.g. 4.2.1.20120417-Final)
    6. mvn clean package
      docs are built and can be uploaded (see bellow: Uploaded documentation structure)
    7. ../build/scripts/change_version.sh -r -o {release_version} -n {next_development_version}
      (e.g. 4.2.1.Final -> 4.3.0-SNAPSHOT)
    8. git add -A
      git commit -m "changing to next development version: {next_development_version}"
      (e.g. 4.3.0-SNAPSHOT)
    9. git push origin {tag}
      git push origin develop:develop
    10. only in case of Final release:
      git checkout master
      git rebase {tag}
      git push origin master:master
      
      (e.g. 4.2.1.20120417-Final)

     

    Generate documentation for maven-resources-plugin

     

    After release of core framework (only for Final releases):

     

    1. go to cdk/maven-resources-plugin/
    2. run mvn site:site
    Uploaded documentation structure

     

    The documentation should be uploaded to release-specific directory with following structure (the artifacts to upload mentioned in second column):

     

    /Component_Reference                docs/Component_Reference/target/docbook/publish (all content = en_US dir)
                                        command: rsync --protocol=29 --delete -av docs/Component_Reference/target/docbook/publish/ richfaces@filemgmt.jboss.org:/docs_htdocs/richfaces/4.3.X/4.3.0.Final/Component_Reference
    
    /Developer_Guide                    docs/Developer_Guide/target/docbook/publish (all content = en_US dir)
                                        command: rsync --protocol=29 --delete -av docs/Developer_Guide/target/docbook/publish/ richfaces@filemgmt.jboss.org:/docs_htdocs/richfaces/4.3.X/4.3.0.Final/Developer_Guide
    
    /javadoc                               (for docs, use all content of JARs excluding META-INF dir)
         /richfaces-components-api      components/dist/richfaces-components-api/target/richfaces-components-api-${version}-javadoc.jar 
         /richfaces-components-ui       components/dist/richfaces-components-ui/target/richfaces-components-ui-${version}-javadoc.jar
         /richfaces-core-api            core/api/target/richfaces-core-api-${version}-javadoc.jar
         /richfaces-core-impl           core/impl/target/richfaces-core-impl-${version}-javadoc.jar
    /vdldoc                             components/dist/richfaces-components-ui/target/richfaces-components-ui-${version}-vdldocs.jar (content of /richfaces-vdl-documentation/ dir inside JAR)
    /maven-richfaces-resources-plugin   cdk/maven-resources-plugin/target/site