Commit Comments: A Conversation with your Future Self

I frequently find myself searching subversion commit logs trying to find hints as to why certain "features/bugs" where introduced and why. Usually this results in wasting several hours and almost every time I get frustrated with a lack of dialogue in commit comments. I can't stress enough the importance of this often over looked feature when committing changes. A lot of developers look at it like a 30 second burden that's preventing them from taking lunch earlier. What they really should be doing is pretending it's a conversation with their future self. Six months from now you're most likely going to be seeing those comments, or lack of, wondering why you made that change. It's in that moment I'd rather have a very descriptive summary of what changed and why verses diff'in every version known to man.

I'm not asking for a Kevin Costner script, just be a little more specific. On average, my comments are 1-3 sentences. For the important changes, I've used paragraphs before. Comments with fewer than 5 words drive me nuts, and I have seen a lot of them.

Ever seen a movie where campers make a trail using something like marshmallows so they can find their way back? Think of your commit comments like marshmallows helping you unravel the mystery of an issue and start developing the habit of providing more descriptive commit comments.

Other Useful Tools
One of the tools I have grown fond of is the Jira subversion plugin. Our team uses Jira as our issue tracking system. Nothing gets committed without a Jira number. This is enforced using a subversion pre-commit hook, so every developer has to start their comment with a Jira number. Then in Jira, there is a Subversion Commits link at the bottom to where anyone can view the files changes and their comments.

Using the subversion pre-commit hook has another added bonus, which is using the Hudson Jira Plugin. After a successful build, hudson will extract the Jira number(s) from the commit comments and add a comment to the Jira stating it was integrated at a specific build # and includes a link.

Accessing Hudson Variables with a Free-Style Project

Here is a great article on creating a manifest file containing hudson variables so that you can know exactly what build number and svn number built your artifact. However, in my case I wanted to create a properties file under my maven2 project under src/main/resources and let maven filtering take care of the rest. But for some reason it wouldn't work. After some further research, I eventually found out that free-style projects appear to not work the same as a maven2 project in hudson when trying to access hudson variables.

In summary, hudson variables work as expected when you create a maven2 project in hudson. With a free-style project you have to perform an extra step. Why, I don't know; I am sure there is a good reason. It's just too late to figure it out.

Here are the extra steps you can follow to create a properties file containing hudson values.

Update POM
In your projects POM or parent POM add the following properties at the bottom

<project>
 ....
 <properties>
     <build.number>${BUILD_NUMBER}</build.number>
     <build.id>${BUILD_ID}</build.id>
     <job.name>${JOB_NAME}</job.name>
     <build.tag>${BUILD_TAG}</build.tag>
     <executor.number>${EXECUTOR_NUMBER}</executor.number>
     <workspace>${WORKSPACE}</workspace>
     <hudson.url>${HUDSON_URL}</hudson.url>
     <svn.revision>${SVN_REVISION}</svn.revision>
 </properties>
</project>

Create a properties file
Create a application.properties file under your maven2 projects src/main/resources directory.

Now add this to it

build.number=${build.number}
build.id=${build.id}
job.name=${job.name}
build.tag=${build.tag}
executor.number=${executor.number}
workspace=${workspace}
hudson.url=${hudson.url}
svn.revision=${svn.revision}

Using Maven War Overlays to extend Hudson

I just recently found out about one of the neatest features of the maven-war-plugin called WAR Overlays. Basically it provides a very simple way to merge multiple WARs together to create an Uber WAR. You simply add a WAR as a dependency in your POM verses adding a JAR, and the maven-war-plugin will take care of the rest. My team uses this ability to extend the JSPWiki WAR to add in our wiki pages. The result is an Uber WAR including the JSPWiki stuff and our wiki pages. Then when a new JSPWiki WAR is available we just update the dependency version in our POM.

So for an example, I am going to demonstrate extending my favorite CI tool Hudson since it's freaking awesome and is downloaded as a WAR. Don't try this at home since hudson already provides the ability to extend it using plugins (which also rocks by the way).

Create a Simple WAR Project
First, create a war project using maven-archetypes. Execute mvn archetype:generate and select #18. Run mvn clean install to ensure it builds correctly (I am using maven v2.0.9).

Install hudson into local repository
Next we need to be able to consume the hudson war in our pom and since I am unware of the hudson war being available on any external repository we are going to just install it manually into our local m2 repository.

• Download the latest hudson war
• Install hudson.war into your local repository using the mvn install plugin by running: mvn install:install-file -Dfile=hudson.war -DgroupId=hudson -DartifactId=hudson -Dversion=1.0 -Dpackaging=war
  

Consume the hudson.war in your pom
Open up your war's parent pom and add the hudson war as a dependency.

<dependency>
  <groupId>hudson</groupId>
  <artifactId>hudson</artifactId>
  <version>1.0</version>
  <type>war</type>
  <scope>runtime</scope>
</dependency>

Next, since we want to run hudson in embedded mode without a container we need to add to the generated manifest file the Main class since I am too lazy to figure out how to include the original hudson manifest file (even though I am sure its possible). Include the following in your build section:

<build>
<finalName>mywar</finalName>
<plugins>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <archive>
      <manifestEntries>
        <Main-Class>Main</Main-Class>
      </manifestEntries>
    </archive>
  </configuration>
 </plugin>
</plugins>
</build>

Build and Run it
Now build the war again: mvn clean install. And your WAR should be merged with the hudson war. In fact for verification, your simple war contained an index.jsp under src/main/webapp and if you extract the war under target you will see your index.jsp.

Run: java -jar target/mywar.war
and go to: http://localhost:8080/index.jsp

If you are doing this on a serious level, you might want to look into the maven-cargo-plugins ability to create Uber wars.

Volunteering as Hudson OpenSolaris IPS maintainer

Starting with an open request by Hudson project lead Kohsuke Kawaguchi, I volunteered to be an OpenSolaris IPS package maintainer for Hudson. Not sure I am qualified but I am a huge Hudson advocate and am looking forward to the challenge.

My main goals are to:

• Learn more about how open source communities work
• Go in the opposite direction of my comfort zone and learn something new

Stay tuned on this Hudson wiki page I have created to document this effort.