This document describes some basic
principles to follow when 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. In general, you should should create a .zip file that
contains all changed files. This .zip should mirror the structure of the Barracuda source
tree so that its contents can be easily extracted and put into place. In addition, you
should provide a detailed explanation of what you have changed and why.
Within the code itself, here's how you should comment your changes.
Add a comments section at the top of source files called "Changes
History" or something like. When you make changes to a file you should add comments
in this section describing what you changed and the particular "moniker" under
which you made the changes. For instance:
* Changes History
* -----------------------
* csc_20010516 - Simple change to do blah...
* ...
A moniker is just a unique stamp, usually composed of
initials+date(optionally + sequence number). So if I made a particular set of changes, my
moniker might look like //csc_20010516 or //csc_20010516.1 This makes it easy to search
source to find all places touched by a change.
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.
If I'm changing a single line of code I'd do it like this:
//csc_20010516 doThis();
doThat(); //csc_20010516
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_20010516_start
// doThis1();
// doThis2();
// doThis3();
for (int i=0; i<100; i++) {
doThat1();
}
//csc_20010516_end
Here its easy to see what happened: the first three lines were commented
out, and replaced by a simple for loop.
Update the master change list: in this case Barracuda\docs\changes.html.
Here's where you associate the moniker with the overriding purpose of the changes. This
allows people to look in one place to find what's changed/when, and then they can search
the source for specific changes that relate to it.
|