RichFaces Development Branch Usage Example

Version 2

    The RichFaces project follows the coding guidelines outlined in <link> and part of that process is using development branches for any change to the project trunk that is more than a minor, well understood bug fix or update.

    Introduction

    This document will walk though an example of using svnmerge.py tool to help manage your development branches.  In this example we are going to be working on an update that is represented by the jira RF-0001.  It does not matter what the update is for.  This example does assume you have svnmerge.py available at the command line.

     

    For complete instructions on using svnmerge.py see: http://www.orcaware.com/svn/wiki/Svnmerge.py .  If JBoss SVN server version updates 1.5+, we'll be able to just using SVN's tools for merging, but for now svnmerge.py is doing the job

    Create The Development Branch

    The first step is to create your development branch.  For our example it means we will be using the following commend:

    Checkout The Development Branch

    This is easy enough, find a location where you want to check out your branch ( typically in a base project directory called "svn" for me ).  Then run:
    svn co https://svn.jboss.org/repos/richfaces/branches/RF-0001 RF-0001
    You now have a directory /RF-0001 filled with the contents of you branch.

    Initialize Your Branch

    The very first thing you should do is let svnmerge.py initialize the merge tracking.  Move into the /RF-0001 directory and execute the following command:
    svnmerge.py init
    This will create a a tracking file and a comment file for you.  Just commit and then remove the comment file using:
    svn ci -F svnmerge-commit-message.txt
    rm svnmerge-commit-message.txt

    Do You Development Stuff

    Use whatever IDE/Tool system etc... you want at this point and make what ever changes are needed in the new development branch.

    Merge Out From Trunk

    Periodically, and especially before you merge back to trunk, you much first merge out from trunk.  This is where svnmerge does its work.
    In your development branch ( with everything checked in) execute:
    svnmerge.py merge
    At this point you'll have all the changes from trunk in your working directory, but not checked in.  Now resolve any conflicts, and make sure your development branch still builds.
    Then commit your changes using the svnmerge comment file like below, and keep on working...
    svn ci -F svnmerge-commit-message.txt
    rm svnmerge-commit-message.txt

    Merge Back To Trunk

    MAKE SURE TO MERGE FROM TRUNK TO DEV BRANCH AND RESOLVE ANY ISSUES IN DEV BRANCH BEFORE DOING THIS
    So now you have finished your work, and your update is done.  Now you need to re-integrate with trunk.
    • First create a clean checkout of trunk
      • This is recommended, but not always needed
      • Just make sure your trunk has no location changes, and run "svn update ." first

     

    Now in your trunk run the following commend

    svnmerge.py init https://svn.jboss.org/repos/richfaces/branches/RF-0001
    Then commit your changes using the svnmerge comment file created:
    svn ci -F svnmerge-commit-message.txt
    rm svnmerge-commit-message.txt
    Now you are ready to merge back to trunk.  Again in the /trunk run:
    svnmerge.py merge --bidirectional
    Note that sometime you may need to specify a branch name like below, don't worry it will tell you.
    svnmerge.py merge --bidirectional -S /RF-0001
    Now its time to Resolve any conflicts in the trunk.  Hopefully there will not be many ( or any ) since you did merge out from trunk right before you did this - right?
    Now run a full build with tests, and commit your updates with, you guessed it:
    svn ci -F svnmerge-commit-message.txt
    rm svnmerge-commit-message.txt

    Cleaning Up Your Branch

    Like every good kid we have to clean up now.
    In the trunk from above run:
    svnmerge.py uninit -S RF-0001
    svn ci -F svnmerge-commit-message.txt
    rm svnmerge-commit-message.txt
    
    Then it is good practice to remove you development branch from SVN:
    svn rm https://svn.jboss.org/repos/richfaces/branches/RF-0001 -m "RF-0001 development branch now closed"

     

    And you done, time for the next one, or a beer ;-)