Since SCM changes are integrated with bug-tracking, it is possible to produce a list of changes that occured for a particular version of a software at a level that's higher than source changes.
ChangeLog information derived strictly from the SCM system, such as a report produced using the cvs2cl tool for CVS or using 'svn log' in Subversion, is overly detailed. It describes software changesets at a lower level, which interests mostly developers. It is of little value to a user simply interested in a summary of added features. Moreover, when multiple changesets are committed in response to a defect, such a document becomes lengthy. It takes considerable time to follow the history of changes and decipher if, or how, a defect was corrected.
Instead, a VDD reports at a higher level a summary of the features/defects worked on and why, using information recorded in the bug-tracking system. It provides additional useful information such as resolution status, bug owner, severity, and priority. It also reports what changes occured at a lower level in the SCM system per bug, effectively superseding ChangeLog documents produced strictly from the SCM system. Without integration of SCM with bug-tracking, this level of detail in a release document would not be possible.
Given two SCM label names (tag or branch names), this tool
queries the SCM system for the dates the labels were applied. It
then queries the bug-tracking system to produce a report of the
bugs worked between that date range. A VDD can additionally
reflect decisions of the development team which are not
documented in the SCM logs, such as choosing to not add a
feature, resolving it as WONTFIX
. It may also
display bugs that were added in the period between releases but
not worked yet, alerting users of newly discovered defects.
A VDD can be generated using the command scmbug_vdd_generator.pl. An example producing this document is shown in Figure 7-9.
Figure 7-9. Generating a Version Description Document.
$ scmbug_vdd_generator.pl --scm=Subversion --product=TestProduct \ --repository=file:///tmp/testrepository --from=tags/SCMBUG_RELEASE_0-8-1 \ --to=tags/SCMBUG_RELEASE_0-8-2
The output of this tool is a collection of files. An XML file is produced that contains the result of the VDD query. This file is also transformed using XSLT into a Docbook 4.2 SGML file. Finally, this SGML file is processed using Docbook tools to produce PDF and HTML output.