cool stuff
/src_docs/developers/submitting_changes.html, v125

Submitting Changes

This document describes how to submitting changes to the Barracuda code base. An authorized Barracuda committer will review your changes, identify any changes that need to be made, and then update the source tree. Submit enough high quality patches and you become a candidate for committer status.

Within the code itself, here's how you should comment your changes.

  1. First of all, you need to pick a "moniker" for your changes. Usually, this will be <your initials>_<mmddyy>_<seq number> (eg. csc_052905_1 would be my moniker for my first batch of changes on May 29, 2005; If I were to check in subsequent rounds of changes, I'd just bump the sequence number each time).
     
  2. When changing code, NEVER delete old code. Comment it out so the person reviewing your code can easily see what was there before. Once the reviewer is satisfied with your changes and ready to check them in, he/she may remove the old code. This will help keep the tree clean and understandable.

    Now, whenever I change code, I need to tag it with my moniker. This makes it easy to search source to find all places touched by a change.

    If I'm changing a single line of code I'd do it like this:

    //csc_052905_1    doThis();
        doThat();    //csc_052905_1

    This makes it easy to see that I commented out the first line and replaced it with the second one. Of course additional comments can always be added to make the intent of the change clear (ie. why are the changes being made).

    In the case of multiple line changes, I'll often do something like this:

    //csc_052905_1_start - fix broken logic; should be using for loop instead
    //    doThis1();
    //    doThis2();
    //    doThis3();
        for (int i=0; i<100; i++) {
            doThat1();
        }
    //csc_052905_1_end

    Here its easy to see what happened: the first three lines were commented out, and replaced by a simple for loop. Of course, it would also be helpful to explain WHY the changes were made.
     

  3. Once your changes are complete, update WEB-INF/A_Changes_History.txt to describe what you have changed. Newest stuff goes at the top. Make sure you label your changes with the particular moniker under which you made the changes. For instance:

    ----------------------------------------------------------------------------------------------------
    csc_112805_2 - Moved the /docs tree to /docs_old in prep for new updated docs.

     

  4. If your change will break old code (eg. a 2.x modification that is not backwards compatible w/ 1.x), then you will also need to document that in WEB-INF/A_Changes_Barracuda_2.0.txt.

Once you've done this, run the unit tests to be sure everything passes muster, then .zip all your files you've changed and send them to the list. You should always provide a detailed explanation of what you have changed and why. A committer will review your changes and then apply them to the tree when he/she feels they are ok. Pretty easy, eh?

 


Last Modified: 2006-01-02 15:59:13 -0500 (Mon, 02 Jan 2006)