Inside VSTS

Creating a Release Manifest

A release manifest should be more than a list of all the files in a release; it should also give users a better idea of what features are available.

• By Jeff Levinson
• 01/13/2009

I'm going to partially agree and partially disagree. I think that a better definition of a release manifest is the summary of the released functionality so end users know what the new features of the release are (testers don't mind having this information also). And after all, one of the goals of Team System is to provide business value.

Yes, each of these definitions serve different purposes, but you can get both very easily with Team Foundation Server -- assuming you structure everything appropriately.

Because TFS uses global changeset numbers (by that, I mean the changeset number is unique to the server on which TFS exists), it's simple to create a list of files and their changeset version number that's included in the build. But this can be complicated by the method you're using to promote your code. For this article, let's assume you're using a Branch by Quality model (Dev/QA [or Main, if you prefer]/Prod). In this scenario, you promote code from Dev to QA, and test and release from the QA branch. If you're taking the tips of the QA branch for the release, this is simple: You just apply a label to the latest version and you're good to go. But how about work items? We'll revisit other scenarios later on.

Work items pose something of a problem in TFS given their implementation. Work items aren't part of the branching structure. They don't move when your code moves and they don't have "version" numbers; they simply have history.

Let's look at another simple scenario: You have two work items (Task A and Task B) and you've associated two changesets with each task on the Dev branch (Task A is associated with changeset 1 and 2, and Task B is associated with changeset 3 and 4). Now, when you go to merge the code to the QA branch, this will result in changeset 5, which will be associated with nothing. You can always associate changeset 5 with both Task A and Task B, but imagine if you have a hundred tasks that need to be associated with the merge changeset. Is it easy -- or even possible -- to remember all of the related tasks? And let's not get started on a cherry-pick merge; it becomes a nightmare. Let's solve the problem with a couple of basic, built-in features.

First, I frequently recommend using a custom work item type called "Release." You need very little information in this work item type -- a title (something descriptive such as a release name-like period -- 1st Quarter, January, etc.), build number and label. You can make this fairly complex once you examine all of the permutations, but keep it simple to start. A suggested state flow is shown in Figure 1 (the key word being "suggested"; it may be different for you -- and I can almost guarantee that it will be).

Next, you need to create what I call a "Promotion Build" with Team Build. This build is the same as every other type of build with one exception: You will only run it before moving code from the Dev branch to the QA branch. Why? Well, for one thing, this build will automatically apply a label to all of the code on the Dev branch. For another, you want the build report. The build report contains a list of all changesets and work items that have changed from the last time the Promotion Build ran. To get to the build information, run the build report (Figure 2) and drill in to the appropriate build (Figure 3) to see the details.

Once you have the build, you can then merge from Dev to QA and do a merge by Label using the build label that was created in the previous step. Associate the check-in with the Release work item. In addition, add a hyperlink to the release work item with the URL of the build report for that particular release. (As shown in Figure 4, to get the build report URL, open the Build report and drill down to this particular build and copy the hyperlink from the address bar.) Just note that you'll have to wait an hour for the build report to become available or process the warehouse faster.

If at any point before the release you have to do bug fixes (and virtually everyone has to do this), all of the code that you check in should be associated with the release work item and the bug work item. Now, you have effectively transitioned work items across branches and ensured that any last-minute changes have been associated with the release. It's not necessary to generate a manifest now because users can be sent the work item with the linked build report and changesets; there's no question about either what code is part of a release or what business functionality is part of that release.

It's important to understand that the process will differ depending on your branching and promotion model (for example, if you have a Branch by Feature model, you can assume that this will be a more complicated process). And to be sure, there are other ways to accomplish this that require additional work. But I wanted to present a simple model that could be used right now with no additional cost and only a little bit of additional effort.

From my experience with various tools, Team System is the only tool that really provides the ability, built-in, to understand the business requirements implemented with each new release of code without all of the overhead!