Section 4.7. Tracking Project Changes | Maven: A Developers Notebook (Developers Notebooks)

4.7. Tracking Project Changes

When you're developing a project, it's useful to provide to your users a list of changes between the previous version of the project and the current version. This allows users who are expecting a feature or a bug fix to verify that the enhancement is in the new version. But even more important is the fact that you can regularly publish the progress report, which will keep your users and/or stakeholders spellbound!

4.7.1. How do I do that?

The first solution that comes to mind is to use the Maven Changelog plug-in. It extracts commit logs from your SCM and generates a report. It has a maven.changelog.range property that controls how many days in the past to look when performing the extraction. To use it, add it to your reports section in qotd/core/project.xml:

  <reports>     <report>maven-changelog-plugin</report>     [...]

After executing maven site you'll get a report similar to the one in Figure 4-14.

Figure 4-14. Sample Changelog report showing the last 30 days' worth of SCM commits

The problem with this solution is that commit logs contain lots of information that is not useful for users of your project. Actually, showing all those logs will make it close to impossible for anyone to find out user-related changes. Automatic generation of relevant changes is still a dream!

Thus, you need to hand-edit the changes to make them nice and clean. Maven has a nice Changes plug-in that helps you to do this. To use it, create a qotd/core/xdocs/changes.xml file with the following format (this is an example):

<?xml version="1.0" encoding="UTF-8"?>    <document>   <properties>     <title>Changes</title>   </properties>   <body>     <release version="1.0-SNAPSHOT" date="in SVN">       <action dev="vmassol" type="update">         Restricted the changelog report to only show the changes for the          last week.       </action>     </release>     <release version="0.9" date="2005-03-22" description="Initial release">       <action dev="vmassol" type="fix" issue="QOTDCORE-1">         The changelog report now works with Subversion.       </action>       <action dev="vmassol" type="add">         Initial release. See the features page for more details.       </action>     </release>   </body> </document>

Each release tag corresponds to a version release and each change is described using the action tag. An action can be an addition (type="add"), a removal (type="delete"), an update (type="update"), or a bug fix (type="fix"). As you can see from the preceding code snippet, with the QOTDCORE-1 issue it's also possible to link an action to an issue URL from your issue tracker. The plug-in computes the URL by evaluating the maven.changes.issue.template property which, by default, points to:

maven.changes.issue.template = %URL%/%ISSUE%

The %URL% token is the value of the issueTrackingUrl tag in project.xml, but without the last element in the path. For example, for the core project using Jira as its issue tracker, you have:

<project>   [...]   <issueTrackingUrl>     http://www.mavenbook.org/jira/browse/QOTDCORE   </issueTrackingUrl>   [...]

The %ISSUE% token is the issue number defined in the action tag of changes.xml (QOTDCORE-1 here). Thus, the full URL that is computed by the Changes plug-in is:

http://www.mavenbook.org/jira/browse/QOTDCORE-1

If you're using a bug tracker that doesn't match the default issue template, you'll need to modify the value of maven.changes.issue.template. For example, for Bugzilla you would use:

maven.changes.issue.template =     %URL%/show_bug.cgi?id=%ISSUE%

And you would use:

maven.changes.issue.template =     http://sourceforge.net/support/tracker.php?aid=%ISSUE%

for the SourceForge tracker.

Add the maven-changes-plugin report to your POM reports section and execute maven site to generate the report shown in Figure 4-15.

Figure 4-15. Sample Changes report

One nice additional bonus is that the Changes report generates an RSS feed of the changes. Thus, your project users can add this feed in their favorite Feed Aggregator (SharpReader, FeedDemon, BlogLines, Newz Crawler, etc.), and they'll know right away whenever a change is made!^[6]

^[6] See Vincent's blog post about Source Code Communication at http://tinyurl.com/exbsb.

4.7.2. What about...

...using issue tracking software for change logs?

This is a very good solution that more and more projects are adopting. You'll need to practice what we (the authors) call Issue Driven Development (IDD) to make it work. IDD goes like this: when a task is done, and just before the code is checked in, ensure that a corresponding issue exists in your issue tracker. If there's no issue for this task, create one (unless the modification is a really minor one that the user should not be concerned with). Then, check in the code mentioning the issue number in the check-in comment, and close/resolve the issue. The result of using IDD is that you can ask your issue tracker to generate a representative change log because all the important changes have an associated issue.