Release-Based Configuration Management

1. Document Purpose

1.1 Scope

The scope of this document is limited to describing and defining a Release-Based Version Control process for managing software assets.

1.2 Objective

The objective of this document is to define concepts, terms, processes, and procedures that provide guidelines to manage the development of their software assets as complete releases. Release-Based CM provides the mechanisms to support multiple lines of development, dynamic and static releases, and promotions.

1.3 Intended Audience

This document is intended for the SCM administrator who will be responsible for implementing and maintaining these processes.

2. Definitions

Release (n): A Release is a collection of specific Revisions of all Components that exist in a software project at a given point in time. There are two types of Releases: dynamic and static.

Dynamic Release (n): A Dynamic Release, also known as a Line of Development (LOD), consists of the most current revisions for the set of components that exist in a software project at a given point in time. An important fact about dynamic releases is that they contain only source components but no targets. Most Version Control tools represent Dynamic Releases as the "tip" of an active branch of development. Each time a developer "checks-in" a component to an active branch, the tip of that branch and therefore the Dynamic Release which it represents, changes dynamically. Hence the term Dynamic Release. A special label called a "floating label" can be attached to an active branch of development to provide a symbolic name that identifies the Dynamic Release. Unlike other labels that are "fixed" to a specific Revision, floating labels "float" to the tip of the branch of development to which they are attached. Because Dynamic Releases change each time a file is "checked-in", a Dynamic Release is NEVER guaranteed to be the same from one moment to another.

Static Release (n): A Static Release, also know as a "snapshot", consists of specific revisions from the set components that exist in a software project at a given point in time. Static Releases contain both sources and platform specific targets. Static Releases are "snapshots" of a Line of Development at a specific point in time. Specifically, Static Releases are created by attaching a Static Release Label to the same revision that contains the Dynamic Release Label that represents the Dynamic Release from which the Static Release is being created. Static Releases should be considered immutable. Once the static release is created in the version control tool, it never changes. That is not to say that software development stops with respect to a particular application. It means that once a static release is defined, it is never redefined. Static releases are useful to a project for identifying the exact state of an application at a specific moment in time. Because Static Releases are considered immutable, a Static Release is ALWAYS guaranteed to be the same from one moment to another.

Promotion (v): A promotion is the process by which a static release is copied to a higher promotion level. The purpose of promoting a static release is to convey to the development organization that a release has achieved a predefined level of quality or is now designated as appropriate for a particular use.

Demotion (v): A demotion is the process by which a static release is copied to a lower promotion level. The purpose of demoting a static release is to create a "starting point" for future LODs or bug fix releases. Generally, a "production" release is demoted to "development".

Promotion Level (n): Promotion Levels are an ordinal series of logical designators that are used in release labels to signify that a release has achieved a predetermined level of quality and that the release can be used for the particular purpose designated by the promotion level. A common series of promotion levels is "dev", "tst", and "prd". All dynamic releases (LODs) are in the lowest promotion level ("dev"). All static releases ("snapshots") begin in the lowest promotion level ("dev") and are promoted to higher levels as their quality is certified.

Component (n): A component is a file based software asset that is being managed as part of a software project by the Version Control system.

A list of components might include:

• Requirements Documents
• Design Documents
• Source Code
• Third Party Libraries
• Configuration Files
• Drivers
• Unit Test Cases
• Unit Test Data
• Unit Test Output
• Release Notes
• Intermediate Targets
• Final Targets
• Programmers Guide
• Service Developer Guide
• System Test Plan
• System Test Cases
• System Test Data
• System Test Output
• System Test Report
• Traceability Matrix
• Installation Scripts
• Configuration Scripts
• Maintenance Scripts
• Installation Guide
• Administration Guide
• User’s Guide
• Disaster Recovery Plan
• Make Configuration Files

3. Process Overview

3.1 Process Description

Release-Based Management is a Software Configuration Management practice where all of the components for a specific software project are managed in logical units called Releases. Releases are comprised of specific Revisions of all components created for the software project regardless of whether those components are used at design-time, build-time, or run-time. Each component in a Release is necessary at some point for the project to function correctly throughout the development cycle. As a development project progresses, many of its components will change. Some of these components may change frequently, others rarely or not at all. It is important that as these components change, the appropriate Revision of all required components is managed in the Version Control tool as a single unit - a Release.

A typical example of using Release-Based CM is when an end-user finds a problem in the current production installation of an application; it is that release of the software that is identified as being defective. It is that release of the software that the developer must install and investigate to confirm the problem. When the developer finds that the problem is in the application's run-time initialization file and modifies it, it is this entire release that is promoted to testing - even though no other files have been modified. While quality assurance may have a test suite designed to exercise only the reported production problem, it is the entire release that they must install and test. When quality assurance promotes the new release to production, it is the entire release that they are promoting - not the application's run-time initialization file. Promotions will be discussed in greater detail later in this document.

3.2 Sub-projects and their corresponding sub-releases

A single software project may be composed of several sub-projects or sub-components, each of which may require their own release schedule. That is, a project may be composed of a front-end user-interface component, a back-end database component, and a third party message servicing component. Each component can be written in different computer language; each can be built and tested (to some extent) independent of the others; and each can be on independent release and promotion schedules. However, at some point those components must be integrated together to create the original software project which can now be called a "super-project." If each sub-project has its own release values, it is a collection of those sub-releases (one for each sub-project) which constitutes a release of the super-project. Promotions of super-projects will be discussed later in this document.

4. Specific Process Discussion

4.1 Determine Release Label Format

The process of Release-Based CM is accomplished by using release labels in a version control tool . Therefore the first step in implementing a Release-Based CM process is to determine the format of the release labels. Labels are provided by the version control system, and are simply text strings that can be assigned to any revision of a component under version control. In the case of static releases, the SCM Administrator assigns a static release label to specific revisions of all the files in a corresponding set of application archives. This allows for easy identification of all the components that make up a specific "release" of the application. These labels, referred to as "release labels", are critical in Release-Based development. Once assigned, this label will be used throughout the life cycle to refer to the exact set of file revisions that constitute that release. Any downstream systems or communications will refer to a release by its release label instead of specifying a specific revision number per file.

Given the importance of release labels, the SCM team is the only group with sufficient privileges to assign and manipulate labels. The creation or promotion of a release is up to other groups as discussed in the Promotions section. A SCM Administrator, however, can only perform the assignment of the release label after the appropriate Development Group makes the release request.

Although a single text string, the release label is comprised of several components, or fields, delimited with an underscore. Each field within the label contains meaningful information. Specifically, the static release label format is as follows:

<promotion_level>_<release_number>_<build_number>
_<platform_OS>_<confidence_level>_<timestamp>

where,

<promotion_level> is one of either 'dev', 'int', 'test', or ‘prd’. All static releases begin as Development and then are promoted through the ranks.
<release_number> is the marketing release number for this version of the application. This number will be in the form of X-Y-Z where X is the major component, Y is the minor component, and Z is the patch number.
<build_number> is the number of builds that have been performed for the current <release_number>. This field always starts at 1. This field is incremented by one each time the SCM Administrator attempts to build
<platform_OS> is the platform and operating system including its version number.
<confidence_level> is the degree of confidence that this release will function as advertised. This must be one of either 'a' for alpha, 'b' for beta, or 'ga' for general availability.
<timestamp> the date that this release was created. This will be in the form of YYYYMMDD where YYYY is the year, MM is the month (1-12), and DD is the day.

An example of a static release label through the promotion cycle looks like:

dev_X-Y-Z_1_<platform_OS>_a_YYYYMMDD

In the case of dynamic releases, the SCM Administrator assigns a special label called a floating label to a specific line of development (branch) within each corresponding archive of an application. Furthermore, when accessing source members via a floating label, the latest revision of the line of development is returned from each corresponding archive. Since a dynamic release is redefined each time a developer checks in source against the corresponding line of development, a floating label gives the Development Staff the capability of accessing the most current code for that given line of development.

Given the importance of floating labels, the SCM team is the only group with sufficient privileges to assign dynamic release labels. The dynamic release label format is a subset of the static release format. The subset consists of the first two field of the static release label. The dynamic release label format is as follows:

<promotion_level>_<release_number>

where,

<promotion_level> is always set to "dev" (Development).
<release_number> is the marketing release number for this version of the application. This number will be in the form of X-Y-Z where X is the major component, Y is the minor component, and Z is the patch number.

In the case of dynamic releases, it is important to understand that <promotion_level> is always set to "dev" which corresponds to the Development promotion level. This forces all changes to start in Development within the version control tool.

4.2 Create LODs

Once a release label format has been determined, The SCM administrator must create at least one Line of Development (LOD) in the version control tool using the LOD release label format discussed earlier. This is usually implemented with "floating labels" or some other mechanism that will dynamically assign a release label to the latest revision on a LOD or branch. Many version control tools will default all operations to a specific branch without having to specify a "floating" LOD label, but it is a mistake to rely on this behavior because it does not allow for multiple LODs or a clear connection between the LOD and subsequent static releases created from the LOD. While the discussion of managing multiple LODs is beyond the scope of this document, it is important to use "floating" LOD labels to enable this process to support multiple LODs.

4.3 Manage The LODs

Once an LOD has been created, development can begin. The process of managing the LOD requires the project manager to assign coding deliverables to be completed in a specific order within a timeline to implement the project’s pending change requests. The source and priorities of the change request are determined by the project’s change request process. Once a series of change requests are approved to be included in the next release, the project manager must allocate the deliverables necessary to implement the changes based on technical issues and resource allocation constraints.

Regardless of which changes are destined for a particular release, one of the most important aspects of managing the LODs is determining when will official releases/builds will occur. The two choices the project manager has for scheduling builds are periodic and on-demand builds. Periodic builds are scheduled to occur on a regular reoccurring basis while on-demand builds are scheduled on an ad-hoc basis only when deemed necessary. While both have their place in software development, periodic builds provide benefits to the project beyond the obvious. Regardless of which is chosen, the build process should be identical.

4.4 Promote The Releases

Once a build has occurred, a promotion is the act of moving a static release created by the build process from one stage of its life cycle to the next. This does not represent a physical move (installation) within the version control tool, but rather a logical determination that the software is ready for the next stage. The life cycle "stages" that a software application moves through are referred to as "promotion levels".

All software applications developed under control of the SCM system should adhere to a predetermined scheme. A four-tier promotion scheme (i.e. there are four promotion levels within the life cycle) might be:

• Development
• Integration
• Test
• Production

When a static release is promoted, the entire static release is promoted, not individual files or a subset of project files. All static releases, including promoted releases, are identified in the version control tool by static release labels. Once created, the label identifies the release from that point forward.

When a super-project is promoted, all of its sub-projects should be at least at the same promotion level. For example, if you promote a super-project to Test, then all of its sub-projects should be at the Test or Production level. They may have reached this level prior to the super-project promotion or they may be promoted at the same time as the super-project.

The group responsible for instigating a promotion differs according to the promotion level being assigned. All official releases originate in Development and are assigned a development promotion level. Build management determines and executes a build schedule and therefore would promote a release to the Integration promotion level. System Test determines and executes a test schedule and therefore would promote a release to the Test promotion level. A Change Control Board (or some other equivalent body) determines and executes a delivery schedule and therefore would promote a release to the Production promotion level. Likewise, each department mentioned can instigate a demotion from the same level in which the promotion results.

While the decision to promote from one promotion level to the next is the responsibility of those groups indicated above, it is the SCM Administrator that actually assigns the promotion level to a release. This is achieved through the version control system.

It is important to realize the distinction between a software release that has achieved a specific promotion level and the physical installation of that release. The fact that a release has been promoted to a certain level does not mean that it has been installed into a location designed to support the requirements associated with that promotion level – only that it has been approved for installation into such an environment. The only place that a release at any promotion level is guaranteed to exist, is in the version control system itself. Where, when, how, and even if a release actually goes from the version control system to installation in a particular environment is independent of the promotion itself.

5. CMM Criteria

This process contributes to CMM level 2 compliance as recommended by the SCM KPA by ensuring that the following capabilities are satisfied:

• Commitment to perform
  • Commitment 1 -- The project follows a written organizational policy for implementing software configuration management (SCM).
• Ability to perform
  • Ability 4 -- Members of the SCM group are trained in the objectives, procedures, and methods for performing their SCM activities.
  • Ability 5 -- Members of the software engineering group and other software-related groups are trained to perform their SCM activities.
• Activities performed
  • Activity 1 -- A SCM plan is prepared for each software project according to a documented procedure.
  • Activity 2 -- A documented and approved SCM plan is used as the basis for performing the SCM activities.
  • Activity 3 -- A configuration management library system is established as a repository for the software baselines.
  • Activity 4 -- The software work products to be placed under configuration management are identified.
  • Activity 6 -- Changes to baselines are controlled according to a documented procedure.
  • Activity 7 -- Products from the software baseline library are created and their release is controlled according to a documented procedure.
  • Activity 8 -- The status of configuration items/units is recorded according to a documented procedure.
• Measurement and analysis
  • Measurement 1 -- Measurements are made and used to determine the status of the SCM activities.
• Verifying implementation
  • Verification 1 -- The SCM activities are reviewed with senior management on a periodic basis.
  • Verification 2 -- The SCM activities are reviewed with the project manager on both a periodic and event-driven basis.
  • Verification 3 -- The SCM group periodically audits software baselines to verify that they conform to the documentation that defines them.

6. Benefits of Release-Based CM

Software Configuration Management that relies on a release based methodology will present several benefits over a methodology that doesn't. In the absence of a release, the next manageable element is individual components or files. Shear numbers will tell you that managing from the file level will be very time-consuming. Consider a project with hundreds of files: How would you map a change request to the components that need changing? You may be able to identify an executable which needs to change, but how do you identify the files that make up that executable? You would have to pinpoint the exact file up front merely to associate the CR to a tangible element. How would you maintain dependencies across files? Which versions of the header files did we build with these source files? Which versions of these files are required to run the application? Which versions do we give to test? How do we reproduce that application that we delivered to the client last month? The answer to all of these questions is a "release." Change requests can be mapped to a collection of files which comprise a certain function. All files with inter-dependencies would be collected under a release and thus built, tested and deployed together. Reproducing a collection of files is as simple as requesting it by release name.