Guideline: Maintaining Change Histories and Version Numbers
This guideline provides recommendations on how to decide what elements should be versioned, how to record the version of an element (the format of the version code) and how to track what has changed between versions.
Relationships
Main Description

When authoring method elements, it is important to establish some common policies for the versioning of the method elements, including what elements should be versioned, how to record the version of an element (the format of the version code) and how to track what has changed between versions. Maintaining the change histories of elements is important to anyone that uses or depends on the method elements and are interested in understanding how the element has changed between versions, which may require some action on their part.

Determining what will be versioned

It is important to decide what will be versioned. Will method elements, plug-ins, or configurations be versioned, or some combination? Of course, the idea situation is that you track changes at the individual element level and then collect that information at the plug-in and configuration level. However, such version control may not be practical. In general, capturing version and release information at the plug-in level seems to provide the best compromise.

Determining the number of version levels

In general, elements are versioned when they are released, where "released" in this sense means made available to consumers of the elements. There are usually multiple levels of release (for example, major releases and minor releases). It is important to establish common guidelines for when to release the elements and how to distinguish a major release from a minor release. For example, a major release of a plug-in may be the addition of a new core element like a role, task, work product or process, or some major restructuring of those elements. Where a minor release may be the addition of some new guidance, some textual refinements, minor changes to the method content element relationships, or some minor flow adjustments in the processes.

Determining the format of the version indicator

Once you know how many release levels you need to support, you should decide on the format of the version indicator. Will numbers or letters be used, or a combination of both? How will the different release levels represented? An example of a version indicator is X.Y, where X represents a major version and Y represents a minor version.

Capturing the version of an element and the associated changes

In addition to the version indicator itself, it is also important to capture what has changed in an element between versions so that consumers of the element can make any necessary arrangements, which may include refining their extensions of the released element. Such change information be a high-level description of the key changes, not a detailed history of all changes, as the latter is difficult to maintain and to consume.

It is important to decide where to capture the version information (version number, change description) for the elements. Will the version information be captured as part of the element or in a separate database? It is best to maintain that information in a place that is easy to access from the element itself so that it is easy to maintain.

   

Special instructions when authoring in the UMF: When authoring methods that are to exist within the Unified Method Framework (UMF), there are certain conventions that need to be adhered to with regards to release information. For more information, see Guideline: Release Information in the UMF.

More Information