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!
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.
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
Note
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.
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]
...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.
Get Maven: A Developer's Notebook now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.