Managing the Change Control Process with SpiraPlan

by Inflectra on

Overview

This article explains what is change management and how you can implement an effective change control process using SpiraPlan from Inflectra.

Summary

Change Control is the process of handling proposed alterations to items that have been previously designated as fixed.

This means that an item only becomes subject to change control once it has been signed-off, stored in a baseline and placed under configuration control.

This document contains procedures for two types of change control:

  • software change control
  • document change control

The underlying philosophy is the same, however the forms used, and the details of the procedures vary, so they are described separately.

1. Introduction

1.1. Purpose

This procedure defines how change control is handled at Inflectra Corporation.

1.2. Overview

There are two types of change control covered in this document:

  • software change control
  • document change control

The underlying philosophy is the same, however the forms and the details of the procedures vary so they are described separately.

1.3. Definitions

Change Control is the process of handling proposed alterations to items that have been previously designated as fixed. This means that an item only becomes subject to change control once it has been signed-off, stored in a baseline and placed under configuration control. The aim of change control is to ensure that if a signed-off item is changed then:

  • all stakeholders have an opportunity to participate in the control of any subsequent changes
  • all recipients are made aware of any changes that occur
  • there is an audit trail which connects a change to a configuration item to the reason for its change, and which records the participation and authorization of those people concerned with the change.

Proper change control requires definition of the:

  • level of authority required to change each Configuration Item (CI);
  • methods for handling proposals for changing any CI.

As a configuration item passes through unit, integration, system and acceptance tests, a higher level of authority is needed to approve changes. This is called the promotion of a CI. Just as programmers sign off unit tests, team leaders sign off integration tests, and project leaders sign off system tests, so change approval demands a level of authority corresponding to the status of the CI.

Changes occur naturally in the evolution of the software system. This evolution should be planned and implemented using controlled libraries of software and documentation. Changes can also occur because of problems in development or operation. Such changes require backtracking through the life cycle to ensure that the corrections are carried out at the appropriate level (e.g. system design or module design), and with the same degree of quality control as was used for the original development. The level of authority for each change depends on the part to be changed, and on the phase in the lifecycle that has been reached.

1.4. Acronyms

CI Configuration Item

2. Software Change Control

This section of this procedure applies to software that has been placed under configuration management.

Software problems can be reported at any stage in the lifecycle. Problems can fall into a number of categories according to the degree of regression in the life cycle - i.e. how far back you need to go to fix the problem. Problem categories include:

  • operations error;
  • user documentation does not conform to code;
  • code does not conform to design;
  • design does not conform to requirements;
  • new or changed requirements.

Selection of the problem category defines the phase of the lifecycle at which corrective action needs to start.

2.1. Diagnose Problem

2.1.1. Identification of the Problem

If a discrepancy between desired and actual behavior is identified (this covers both “bugs” and modification requests) then a new SpiraPlan incident should be logged in the appropriate project. SpiraPlan incidents are given a unique reference beginning with the prefix “IN”.

The incident should be assigned to the individual responsible for the configuration management of the software (e.g. Maintenance Manager, project Technical Architect - known as the Controller). That individual will maintain a list in SpiraPlan of all such incidents received.

The individual should then arrange for a review of the incident, this may be a bug that needs a fix or an enhancement that is being proposed.

2.1.2. Investigation

The investigation may be performed by the Controller, or any other suitably knowledgeable individual. The investigator should record the results of the investigation in the Comments section of the SpiraPlan incident record.. The suggested action can include no action.

2.1.3. Review investigation results

All parties with a legitimate interest in the software should review the results of the investigation. They may be formally constituted into a Software Change Review Board (SCRB). The Reviewers should indicate whether the recommended action arising from the investigation should be implemented or rejected and they should also give the change request one of the following priority values:

  • Critical – This incident needs to be included either in an immediate hotfix (if safe and practical) or in the next scheduled update to the system.
  • High – This incident is important and should be included in the next scheduled update to the system unless there are mitigating side effects that make that impossible.
  • Medium – This incident should be included in a future update to the system when that particular module is being next updated.
  • Low – This incident should be tracked for now and if we get additional feedback or it affects many customers should be implemented.

If the recommendations are rejected then the Controller should update the SpiraPlan incident with the reasons for rejection for future reference.

If the recommendations are accepted and a decision is made to implement then the process moves on to the next stage – Make changes.

2.2. Make changes

The fix may vary from a simple change to one software module to extensive changes to design, documentation and code. In all cases, the changes need to be tied back to the authorised SpiraPlan incident record. This is done by ensuring that all of the code committed into the appropriate Subversion (SVN) or Git repositories is tagged with the appropriate incident number (e.g. [IN:xxxx]).

2.3. Software Configuration Control

The Controller should triage and assign the raised SpiraPlan incident. The Fix should be allocated to developers and scheduled.

2.3.1. Fix

The software should be fixed in line with the recommendations in the SpiraPlan incident record.

The new version of the software should be stored as a separate version in the configuration management (CM) system (typically SVN or Git) that holds the software. The change to the code should be identified in the relevant code headers, and also in any available comment fields in the CM library. The CM comment should always include the relevant SpiraPlan incident token (e.g. [IN:xxx]) so that the revision will be linked to the SpiraPlan incident record.

2.3.2. Test

Test and verification activities should match the extent of the changes. All code should be tested, but if there are design and documentation changes then these should also be reviewed, and be subject to similar quality control measures as for an original development. The impact of the changes on other areas of the system should be assessed, and if the risk of introducing new problems is significant, then regression tests should be run.

2.4. Release change

Completed changes will be incorporated into a new release of the software. The release may include other changes as well, or may just include the changes required by the one SpiraPlan incident.

The release is tracked in the SpiraPlan incident using the ‘Planned Release’ standard field.

The Controller schedules the fix so that it is included in a controlled release of the revised system. This may be a matter of hours if the fix is an urgent bug-fix to keep the system running, or it may not occur for a number of weeks.

The release may be performed by the Controller or another developer (known as the Releaser). The Releaser should record the summary description of the fix in the public Release Notes for the release (unless the fix is a security issue, in which case no details are shared publicly to maintain system security). The release number should also be recorded on the original SpiraPlan incident under the ‘Verified Release’ field.

The Releaser arranges for the fix to be delivered and, for cloud hosted customers, installed. Following release, if new evidence shows that the fix was not correct, either the incident is reopened or a supplemental incident created. This incident is then managed and tracked as described above.


3. Document Change Control

This section applies to documents (including Requirements) that have been placed under configuration management.

Document Change Control is very similar to Software Change Control; indeed changes to documents are sometimes triggered by a SpiraPlan incident report. However, the following procedure is based on a SpiraPlan incident logged with type ‘Documentation’. This type differentiates the incident from one to do with the software. In general a Bug/Issue incident type is used to record software problems, while an ‘Enhancement’ incident type or a SpiraPlan Requirement is used to record proposed software enhancements.

3.1. Identify Need for Document to be Changed

3.1.1. Identification of the enhancement

If an enhancement to a document (e.g. a change required to a functional specification) is identified then the SpiraPlan incident or requirement should be filed. The incident or requirement is given a unique reference by SpiraPlan (prefixed by “IN” for incidents and “RQ” for requirements). We shall refer to the incident or requirement generically in the remainder of this section as simply an “artifact”.

The artifact should be assigned to the individual responsible for the configuration management of the document (eg Author, project Technical Architect) known as the Controller. That individual should maintain a list of all such forms received, and place a copy of the form into that file.

The individual should then arrange for a review of the artifact, this may be an error that needs correction or an enhancement that is being proposed.

3.1.2. Investigation

The investigation may be performed by the Controller, or any other suitably knowledgeable individual. The investigator should record the results of the investigation in comments section of the SpiraTeam artifact. The suggested action can include no action.

3.1.2.1. Reviewers of the Investigation Results

All parties with a legitimate interest in the document should review the results of the investigation. They may be formally constituted into a Change Review Board (CRB), or may more informally consist of designated representatives from project stakeholders. The Reviewers should indicate whether the recommended action arising from the investigation should be implemented or rejected.

If the recommendations are rejected then the Controller should file the updated SpiraPlan artifact with comments detailing the reasons for the rejection for future reference.

If the recommendations are accepted and a decision is made to implement the change then the process moves on to the next stage: Change document.

3.2. Change document

The amendment to the document is tracked in the SpiraPlan artifact.

3.2.1. Update

The Author should review the artifact, and apply the change requested.

The new version of the document should be stored as a separate version in the configuration management (CM) library that holds the documents (either SpiraPlan, Subversion (SVN) or Git). The change to the document should be identified in the change history and comments section within SpiraPlan.

3.2.2. Review

The author should double-check that the change has been applied consistently and correctly to all relevant documents, but where beneficial a separate individual (known as the Reviewer) should also check the new version of the document. If it appears that the impact of the change on the system could be significant, full review of all other related documentation should be done.

The reviewer completes the review phase of the artifact workflow in SpiraPlan and signs it off when the review is complete.

3.2.3. Release change

The Controller schedules the change so that it is included in a controlled release of the revised document. This may be a matter of hours if the change is urgent and needed to keep the project running to schedule, or it may not occur for a number of weeks.

The release is recorded on the artifact history and comments within SpiraPlan.

The release may be performed by the controller or the project manager (known as the Releaser). The Releaser should record all release details on the artifact history and comments within SpiraPlan.

The Releaser arranges for the new version of the document to be delivered to all its readers.

The Releaser then updates the artifact within SpiraPlan to indicate the change is complete.

Spira Helps You Deliver Better Software, Faster.

Get Started with Spira for Free

And if you have any questions, please email or call us at +1 (202) 558-6885

Free Trial