Ozibug - web based bug tracking


  1. Introduction
  2. Template
  3. Contents
  4. Automation
  5. Conclusion
 

Release notes are an important part of a product release, they contain specific information about a particular product version.

Release notes can make the difference between a simple, straight forward install or a disastrous upgrade that shreds your data and takes days to recover from. They should be able to provide the reader with the information they need to satisfy their questions. The main question always being - why do I need to upgrade ?

A good set of release notes will give the reader confidence in the company, product and version as their software engineering process can be reflected by their release notes. While a bad set of release notes will tell the reader nothing, except that by reading between the lines (or lack thereof) that the software engineering process is not up to scratch.

 
Back to top
 

A release notes template which can be used as a basis for your product release notes will typically contain the following sections. The advantage of using a template is that your release notes will all be in the same format which will ensure that all the necessary information is included. Each item may be included or omitted depending the type of product, project, application or release.

  • System requirements
  • Installation
  • Upgrading
  • Whats new
  • Changes in this release
  • Outstanding issues
  • Known limitations
  • Contact information
 
Back to top
 

The following information describes the sections in more detail.

  • System requirements

    The new release may require additional hardware and resources or perhaps new versions of required (or dependent) software that must be installed first. This section can include supported operating systems or hardware platforms.

  • Installation

    This section should contain notes on installing the product. It might simply point to a separate installation document if it is a lengthy process.

  • Upgrading

    Special notes on upgrading from a previous version should be included in a separate section. These may also need to include notes on upgrading an installation that is several versions old.

    If the instructions are detailed and lengthy then this section might just point to a separate document.

    Also special attention should be paid to data changes (such as database tables) or perhaps the File and Directory structure as these are things which may affect some advanced installations, for example, you might need to get a database administrator to allocate additional table space, etc.

  • Whats New

    This section should give an overview of the new features or enhancements that are included in this release along with the main reason or focus of the release (there should always be a reason for a release !)

    This section (along with the Changes in this release section) should enable the reader to make the decision on whether this upgrade is relevant and necessary for them. This is important as it can save the reader a lot of time.

  • Changes in this release

    Information about the changes and corrections to problems in previous releases can be placed in this section. It can include the bugs that have been corrected and perhaps how they have been corrected. The level of detail and technical content can vary depending on what the product is, for example, a complicated middleware application that has multiple integration points would need a detailed description of each bug fixed including the Bug Number, Symptom, Cause and Correction detail items whereas a simple application such as an editor may list a summary of each correction.

  • Outstanding issues

    This section usually includes minor problems that have been found while testing and creating the release.

  • Known limitations

    This section includes limitations of the product, for example, problems which occur on a specific platform.

  • Contact information

    This section is good for directing specific release oriented questions to desired area. Supply an email address of the person or organization responsible for creating the release. If there is a product web site which contains the latest news and documentation then supply a link to it here so that people can look to find late breaking news and information.

 
Back to top
 

Automatically generating release notes can be a way of saving time and resources.

The information contained in release notes is fairly static except for the Whats new and Changes in this release sections. However, information for these sections is usually contained in the bug tracking system that your company uses.

If you have entered all the information about each bug, and you have a list of the bugs fixed in the release you are making, then it should be easy to generate the information. One way of doing this is by using the reporting features of your bug tracking system to generate a report and then transcribing the information into the notes. Some bug tracking systems allow you to create and manipulate the bug list first and then generate the release notes using a user supplied template, Ozibug is one such system.

 
Back to top
 

Creating good release notes is a fundamental part of the Software Engineering lifecycle process. Spending the time and effort to create the release notes during the test and quality assurance process will return a higher quality product while also reducing support costs.

 
Back to top
 
Back