Friday, June 8, 2012

Release notes generation puzzle


Why a puzzle? It is just about interaction. I want to share my knowledge with you and hope you want to share your knowledge with me. I know you as reader of this blog have lots of wisdom I can learn from.

I know that I'm "copying" the style of Java specialists with this kind of puzzle but I like it, so here we go...


The problem


I will talk about a very simple and useful practice, which I have formalized thanks to the combination of Catel team practices and my own development process automation needs. It isn't a new one and probably you have used it before.

Let start taking a look into the Catel history file, located at %workspace%\doc\history.txt. I just show you a summary for simplification and, why not, I also give you a preview of the next version of Catel.

Catel history
(+) Added
(*) Changed
(-) Removed
(x) Error / bug (fix)

Version 3.2
Release date:

(+) Added IViewModelFactory so the instantiation of view models can now be fully controlled and customized
(+) Added Description property to IMementoSupport to allow a description to the end-user for memento classes
(*) The IOpenFileService now supports multiple files and in WPF it also supports a title
(*) Updated System.Windows.Interactivity.dll for SL5

(x) Fixed issue that views and view models could not be resolved when a naming convention contained 2 or more [UP] constants
Version 3.1

I always dreamed to produce this kind of release notes. But all my previous attempts gave me a strong headache, because sometimes the issue tracker doesn't contain all features/fixes that were born from the "creative" developer process or the version control commit comments just said something like "Merged".

So, where do the history file added/fixed lines comes from?

Read the history file again. You should notice a legend and the very simple technique that allows us to tag the changes and document them over the time.

But it seems like an overwhelming task and requires self-discipline to keep this kind of log up-to-date. Actually we (the Catel team) update this file manually, actually Geert do the most of this updates,  and we also know many teams that do it manually as well.

But this doesn't need to be updated manually. This is the problem that I want to solve and I hope you will share your experience and knowledge with me. The solution is pretty simple but it just become clear to me when I ported the "relevant" commit comment technique (the Catel team practice) to one of my "real live" projects.

Is it to possible generate release notes with a combination of "relevant" commit comment technique, of course a version control system (VCS), an issue tracker system (ITS), and a continuous integration server (CIS) ?

The clues


1)  What is a "relevant" commit comment?

    A "relevant" commit comment is about a commit comment that indicates a feature completion.  It should be related with addition, modification, removal or bug fixing, but just when those goals are actually "Done, Done". Yes you read well, I wrote "Done, Done". A feature is "Done, Done" when is tested, coded, designed or refactored, integrated, it builds, etc. For details read more "The Art of Agile Development".

2) Take a look into the source control page.


The solution

There are several scenarios; the fact is that there are tons of version control systems, issue trackers and continuous integration server. So, I will wait for your solutions for a couple of weeks, you just have to comment here about it.

I want to share my solution with Subversion (VCS), Team Foundation Server (ITS) with Scrum for Team System process template and Team City (CIS) but you will need to wait for my next blog post. The truth is that I still have to implement it ;).

What do you think? Can this problem be solved? I know, you have the answer and I am waiting for it.

Remember a couple of weeks. Please don't hesitate just comment you solution here.