Artifact: Asset Version Policy
A description of how assets should be versioned.
Domains: Asset Governance
Relationships
RolesResponsible: Modified By:
TasksInput To: Output From:
Description
Main Description

Asset Versioning Levels

There are generally two major levels for versioning with assets: the asset version and the artifact version. The artifact version is typically managed and dictated by the source control management (SCM) system, whereas the asset version is generally dictated by the policies of the enterprise and managed by the repository. In some cases, you may want to allow the Repository to dictate, or perhaps suggest the next version number or label of the asset. The image below illustrates these two major levels for versioning.

Two major levels for versioning: asset version and artifact version.

It is necessary to understand the nature of the relationship between the asset repository and the SCM. Some Repositories store the asset artifacts in the Repository, by value, whereas others reference the artifacts in the SCM by storing the references in the repository.

What Asset Changes Constitute A New Version?

When determining the asset versioning policies it is useful to understand the kinds of changes that can happen to assets in the Repository. One way to look at this is to categorize the changes. There are two major kinds of changes, structural changes, and non-structural changes. Structural changes include altering the content of the asset, meaning the artifacts and the asset's relationships. So if the content of an artifact is changed, thereby creating a new version of the artifact in the SCM, and the asset now needs to point to this new version of the artifact, then this would require a new version of the asset.

A relationship between the version 2.5 asset and the version 3 asset.

In the image above a relationship between the version 2.5 asset and the version 3 asset is illustrated. Preserving these relationships between asset versions provides traceability and impact analysis.

Changing or adding relationships to an asset is also considered a structural change, and requires a change in the asset's version. In the first image above, if the XYZ Component had a new relationship to another test asset, say ABC Integration Test, then the XYZ Component version should be updated.

Non-structural changes include those that affect certain metadata of the asset. The metadata structure for assets is described by the OMG Reusable Asset Specification (RAS: www.omg.org). However, some metadata does describe structural aspects of the asset, such as artifact metadata and asset relationship metadata. The image below illustrates some of the candidate non-structural metadata in RAS. The intent is that if the non-structural metadata changes, then no new asset version is required.

Candidate non-structural metadata in RAS.

Using Impact Analysis When Versioning An Asset

When a new asset version is required, conduct an impact analysis to determine those affected by the new version. Those affected include related assets, asset consumers including people, projects, existing applications and perhaps tools.

The related asset section of the asset metadata provides a way to examine impacted assets. However, the Repository and the organization needs to manage other affected parties such as Asset Consumers, Asset Producers and Owners, Sponsors funding the asset, Engagements and Projects using the asset and also software release and build engineers who have included the asset in a software build.

Developing Assets in A Distributed Team Environment

Another key consideration when specifying the asset versioning policy is to understand how an asset is developed in a distributed team environment. There are multiple topologies possible; two are introduced here. In the first topology the asset repository and the SCM are co-located in each site. This topology implies that replication is required for both the Repository as well as for the SCM. If replication occurs, then the issues of asset and artifact site or location ownership needs to be established for asset and artifact versioning to be safely administered.

The asset repository and the SCM are co-located in each site.

In the second topology, a single asset repository exists in the organization with distributed SCMs at each site. The single asset repository references artifacts in the distributed SCMs. There are no asset replication issues to address, but certainly there are issues of artifact replication and ensuring the asset metadata points to the proper location for artifacts.

A single asset repository for the organization with distributed SCMs at each site.