Release (Version) Management is about maintaining and tracking different versions of your project deliverables, along with their planned and actual release schedule and the issues to be resolved in each different version. This is not only applicable to software development, but also to any type of project where some "milestones" need to be reached. For instance, in a construction project, you can track the construction tasks that need to be completed in the construction milestones like "Groundwork", "Walls" or "Roof Construction".
Important note: the words version, milestone and release, plus the words sprint and sub-release are used interchangeably in this article.
Release Management primarily involves:
Defining releases: creating, updating and deleting the project milestones. Breaking them into sprints (if you are an agile team) or sub-releases (if you are not).
Managing the life-cycles of releases: release progress towards status "Released", "End-of-life" or any other status.
Associating work items (tasks, bugs, user stories etc.) with releases: linking work items to releases or sprints in which they were detected, in which they need to get resolved or to which they are related in any sense.
Managing the life-cycles of issues: this is not strictly part of Release Management, but the resolved or open state of work items is used to compute the status of releases.
Adding, Updating and Deleting Releases
Releases are modeled as configuration items in codeBeamer, leveraging the extremely rich CMDB functionality available. Being first-class citizens in the CMDB, releases themselves are very powerful entities:
Releases have their own customizable properties.
Releases have their own life-cycles, optionally driven by customizable workflows.
Releases can have children in any depth to break them into sprint or sub- and sub-sub-releases.
Releases can be commented, they can have attachments.
Releases can have associations to other entities in codeBeamer.
In other words, you have almost the same functionality available for releases as for regular configuration- or work items.
Maintaining releases: you can create, update and delete releases by adding, updating or deleting items in the corresponding configuration tracker.
By default, there is exactly one configuration tracker initialized for this purpose in each newly created project. It is intuitively called "Releases". You can start your release management work adding an item to this tracker, named for example "1.0-beta".
Breaking Releases into Sprints or Subreleases
A sprint is a timeboxed unit of development used in the Scrum framework. In codeBeamer a sprint is always belongs to a release. That is, every child of a release is a sprint in that release.
Consequently, sprints have the same fields, workflows like their parent releases as those are primarily determined by the configuration tracker which encompassed them.
In the Release list, all sprints of a release are listed indented under their parent:
As you see, sprints contribute their metrics (ex: count of outstanding or completed work items) to their parent so that releases carry statistics aggregated from their children.
To create a sprint just click on the New Sprint item under the more menu of the release statistics page. Here you can specify the same properties as when creating a regular release.
For each sprint you can access the Planner, Cardboard, Release Dashboard and Test Coverage using the small icons in the top-right corner of the sprint's box:
You can also include a release into an other release. Just set the Relese field of one of the releases. After including a release into an other their statistics can be computed recursively.
Associating Issues with Detected and Target Releases
After you have submitted your release to the configuration tracker Releases, you can associate work item with it. Set the Release fields of the issues to "1.0-beta" or to the release in which you are going to address them. You can similarly set the Detected in issue fields to the release in which the bugs have been detected.
Please note that both Detected in and Release allow specification of multiple releases. This increases flexibility: for example, a bug can be reported in multiple released product versions and can also be fixed in multiple versions yet to be released.
Tracking Releases: Progress Reports
At this point, you might want to check the status of your currently running releases. For this, please visit the Releases category in your project. This screen gives you a fast and easy-to-understand progress report on your releases, in real time.
Figure: Tasks and Bugs relevant to codeBeamer Release 7.10.0
All current and future releases are shown and their names are on the left-side. To see the list of issues associated with a particular version, just click the expand icon beside the release's name. The issues are listed in descending priority and are color coded to indicate which ones are resolved and which ones are outstanding: green for resolved, white for outstanding.
On the right side all current, future and past releaes are visible and their links are shown within the page for faster navigation. The completed releases don't have their issues displayed by default, to reduce the clutter in the main part of the screen. You can display them, however, any time simply by checking "Show released", in the box on the right of the screen.
Quick Access Links
Hovering over a releases reveals links to other views of that release including:
You can view the release and its subsprints represented as a Gantt chart. For more information have a look at this page.
Figure: Release Gantt Chart on Release Dashboard page
You might see overdue items in the progress information.
Figure: Overdue items indicator
Overdue items also have an additional badge inside their row, like in this example:
Figure: Overdue items indicator inside the table of items
To find out which items are indicated here, click on the release name to get to the Release Details screen, and choose the appropriate filter in the top right part of the page from the Filter menu.
Figure: Setting an Overdue filter
Tracking Releases: Work Items
Release Dashboard page offers a wide array of options to filter the work items in the selected release. First of all it has two different filters to control the visibility of work items.
Figure: Top filter
The first option is pretty straightforward on the top filter, it allows to activate filtering based on work item status. The second option lets you choose between 3 categories, which are:
Do not show Test Runs: As the name suggests it allows all type of work items to be shown, but prevents displaying Test Runs.
Show only Test Runs: Inverse of the previous one, just show the Test Runs in this release.
Show all Tracker Items: Show everything regardless of the type of the work item.
Both filter options from top filter can be used simultaneously.
The right-side filter panel has a couple of panels containing filters in different categories. These filters only allow values, which are present in the currently visible set of work items. For example the following teams are working on the release:
Figure: Right-side filter
The numbers in the cells show the number of work items, which belong to the given filtering option. Only one filter from the right-side panel can be active. It is possible to share a filtered view of a release using the Permament Link option. The result url can be copy/pased from the browser's url bar.
Figure: Permanent link
Work Items might reference others. You can check these references by clicking on the "+" icon before a Work Item.
Figure: Reference Viewer
Note: The icon is only present, when a Work Item has references, You can configure some aspects of the Refernce Viewer under the more / Reference View Settings menu.
Figure: Reference Viewer Settings
To mark a release as released, simply open the release's details, and then choose "Released" in the "Transitions" popup menu. It will move the release to the "Released" state in its workflow. During the transition the Actual Release Date of this version is automatically filled in with the current system time for your convenience.
Completed releases have not necessarily reached the end of their life-cycles. They can be either withdrawn (if you changed your mind and decided not to release them) or moved to the "End of Life" state (to indicate that those releases are not maintained and supported anymore).
The minimalistic default workflow of releases supports only these three states, but please read the next sections about how to implement your own release workflows.
Roadmaps: Future Releases
A release roadmap is the plan of future releases with their scheduling and planned issue sets. This is what you see when looking at the initial state of the Releases category screen.
Release History: Completed Releases
A release history is simply the log of completed releases with their release dates and their fixed issues sets. This is what you see at the bottom part of the release list after checking the "Show released" checkbox.
Generating Release Notes
Writing release notes documents is time consuming work. In codeBeamer, you can generate release notes simply by clicking the Release Notes link in top-right corner of a release box.
In the next screen you can choose in which format you want to generate the document: plain text, wiki or HTML. The results are immediately available and can be copied to product documentation or to a webpage.
The default release notes documents contain simplistic issue lists. To support custom content and formatting, release notes are generated from templates. If you have special content or formatting requirements, please edit the corresponding Velocity templates in the $CODEBEAMER_INSTALLATION_DIRECTORY/tomcat/webapps/cb/config/templates/release-notes directory.
Certain conditions have to be met for listing issues in release notes. This is evaluated by “Meaning” properties assigned to option values of Status and Resolved fields. To make an issue appear in release notes both of the following conditions have to be satisfied:
Status is Resolved or Closed
Resolution is Successful
Please note it is not the name of the option that is getting evaluated but the “Meaning ” property even if they have identical names in certain cases. Properties can be altered on Fields tab of tracer customization by clicking on the Option link of the corresponding field. Attached screenshots demonstrate the “Meaning” property configuration of Status and Resolution fields of the default Bugs tracker. Before making any changes to these settings please refer to the "Status and Resolution Meaning" section of Tracker Workflows wiki page. These settings have direct effect on workflows and their behaviors.
Figure: Option window of Status field of default Bugs tracker
Figure: Editing window of Resolved option of Status field of default Bugs tracker
Figure: Option window of Resolution field of default Bugs tracker
Figure: Editing window of Fixed option of Resolution field of default Bugs tracker
Customizing Release Management
Implementing more complicated Issue-to-Release associations
By default, issues are linked to versions through the Detected in and Release fields. While this is sufficient in most situations, codeBeamer allows implementing more complicated scenarios. Let's see a little more complicated case, where having a single configuration tracker and two issue fields is inefficient.
Say, you are developing an embedded system that consists of two modules, sensor and logic, which are versioned independently. To make it even worse, your customers use multiple combinations of the different module versions. (This is fairly typical in the embedded space.)
To have accurate bug reports, exact versions of both modules must be submitted. If you want to have two separate version categories, one for sensor and one for logic, you can rename the default Release category to Sensor Versions and then add a new configuration tracker called Logic Versions. Now you would add (and later maintain) the versions of the two modules in the right category.
In the issue tracker, rename the Detected in and Release issue fields to Detected Sensor Version and Target Sensor Version, respectively. Add two new custom fields Detected Logic Version and Target Logic Version, which should refer to the Logic Versions category.
That's it! From this point, everything works correctly for both modules, separately.
This sample scenario hopefully illustrates the possibilities, and explains how to implement flexible version tracking.
Customizing the Default Release Workflow
The default workflow for releases is deliberately kept at a bare minimum. codeBeamer enables implementing more complicated workflows to manage releases easily.
Release workflows are identical with regular tracker workflows under the hood, so please read the Tracker Workflows page for more details about how to use and configure workflows.