When a software team releases a version of its software, it is often requested to prepare a document describing that version. When the software is delivered to a specific client (e.g., the government), you must attach a Version Description Document (VDD). If the software is released to the general public, it is usually accompanied by Release Notes.
In any case, such a document must contain a list of changes introduced in that version and a list of bugs fixed. It may also contain a list of issues, which are known but not yet fixed.
Where do you find all this information? Of course you may scratch your head and remember all the changes you have made. Or you can ask your colleagues. Or, if your team is well-managed, you can find it all in your issue tracking system, like Bugzilla, Jira or GitLab.
OK, assume you have an issue tracking system, say Jira. How do you prepare your VDD? First, you create a Word document. Then you run queries in Jira asking for features completed since the previous release, bugs fixed, issues open but not yet fixed. You copy results of each query from Jira and paste them to your VDD. (Make sure you haven’t copied columns you don’t want in the document.) Is it an easy approach? Not sure… Elegant? Certainly not! And what if you have to do it every few months?..
Indeed, that was what Jennifer of Northbound Software (all names are changed) had to do each time her group released a version. Northbound Software has a number of customers, and there are releases for each customer, and for each release Jennifer had to prepare a VDD. It was so tedious, that she asked us at ALM Toolbox to automate the task.
We have written a Python script, which used Jira API to extract information from the JIRA project and the python-docx library to create Word documents.
Now all Jennifer has to do is to prepare a small parameter file which tells our script for what version number to build the VDD, when was released the previous version (so that only features added since then would be mentioned in the VDD), etc.
Attached is an example of a VDD created by our script (all information is totally fictitious).
By the way, note that each row contains a link to the corresponding Jira issue.
What did Jennifer and her company gain?
- Jennifer is freed from the tedious task of preparing VDDs manually and now has time for more productive tasks.
- Software versions can be released faster, as now there is no need to wait for VDDs.
- Avoidance of human errors.
What is our know-how (just a part of it)?
- We know how to extract data from GitLab, Jira, Bitbucket or any other tool, which exposes an API.
- We can build programmatically Word documents and Excel sheets in any customer-defined format, integrating data from the above tools.
Written by Alex Karnovsky, ALM-Toolbox
