I was talking last week about using XML to act as an intermediate step in building your documentation (Automating Documentation and Automating Documentation Part 2). It dawned on me that I could also share my technique for building release notes.
I use Subversion. I’ve gotten positively anal about commenting when I make changes. So if you were to take the history of my SVN commits, they make pretty decent release notes. The trick is to grab them and automatically turn them into documentation.
SVN makes this pretty easy. It takes one command to grab all of the changes. It takes one switch to make the change export as XML. Once that is done, manipulating the content in ColdFusion is a breeze. I do it using <cfexecute> and svn.exe, below is my code:
<cfset svn.wc = “[path to svn working copy]”
/>
<cfset svn.exe = “[path to svn executable]”
/>
<!— -v = verbose –xml outputs it as xml —>
<cfset svn.arg = “log #svn.wc# -v –xml”
/>
<!— get contents of SVN history —>
<cfexecute name=“#svn.exe#”
arguments=“#svn.arg#”
timeout=“30”
variable=“changes”
/>
<cfset changes = XMLParse(changes) />
<cfoutput>
<cfloop
index=“i”
from=“1”
to=“#arrayLen(changes.log.logEntry)#”>
<!— lxml = LoopLocalXML (shorted for display) —>
<cfset lXML = changes.log.logEntry[i] />
<dl>
<dt>#lXML.XmlAttributes.revision#</st>
<dd>
<ul>
<li>#lXML.author.XMLText#</li>
<li>#lXML.date.XMLText#</li>
<li>#ParagraphFormat(lXML.msg.XMLText)#</li>
</ul>
<p>Files Effected</p>
<ul>
<cfloop
index=“j”
from=“1”
to=“#arraylen(lXML.paths.path)#”>
<!— lPaths = LoopLocalpaths —>
<cfset lPaths = lXML.paths.path[j] />
<li>
#lPaths.xmltext#
(#lPaths.xmlattributes.action#)
</li>
</cfloop>
</ul>
</dd>
</dl>
</cfloop>
</cfoutput>
In my build process, I use <cfsavecontent> and <cffile> to write the content to a file, and then use ANT to call the CFML page that creates the release notes – voila, release notes are now part of every build, with no extra work on my part.
tpryan.blog 
Must find time to implement! 🙂
LikeLike
I think your heading slightly down the wrong track here, SVN commit messages are intended for developer level info, not for the end user.
Making release notes off your commits would make me likely to commit less often and in big chunks, making rolling back harder.
This all relates back to the discussions on commenting your code as discussed here http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html
I use JIRA and include a task key in every commit message which ties back to a task in the project database. This task contains a nice title and description and can capture much more useful information (ie business related information).
JIRA then parses all SVN commit messages and ties them back into the associated task.
You can then produce release notes based on a release (defined by the associated task in the project db) and just not a date range
At the end of the day it comes down to personal preference.
That said, useful stuff..have you looked into the JavaSVN library?
LikeLike
@Zac We might be playing with semantics here. “Release notes” might not be exactly what I’m creating. The documentation I use this for does go to other developers, so maybe I’m not quite getting the perfect term.
I’ve fooled around withe the JavaSVN stuff but bang for my effort just calling the executable from CF has given me great results.
LikeLike
I often read your blog and always find it very interesting. Thought it was about time i let you know…Keep up the great work
LikeLike