Library Versioning

Clinical Quality Language provides the ability to define libraries of declarations that are used to describe the criteria and other aspects of a measure. In addition, this capability allows shared declarations to be used by multiple measures, as well as by artifacts in other domains.

With this flexibility comes the need to track dependencies from measures as well as from one library to another. Versioning is an important tool for maintaining those dependencies. Although the CQL specification provides the ability to specify versions within libraries, it does not specify how to interpret those version identifiers. This proposal recommends an approach to versioning libraries used within CQL-Based HQMF Measures to help track and manage dependencies. The proposal recommended here is based on the Apache APR Versioning Scheme.

Because CQL libraries can contain both public and private components, there are three main types of changes that can be made to a library. First, a library can be changed in a way that would alter the public usage of its components. Second, a library can be changed by adding new components or functionality but without changing existing components. And third, a library can be changed in a way that does not impact the public usage of its components at all, but only corrects or improves the original intended functionality.

By exposing version numbers that identify all three types of changes, libraries can be versioned in a way that makes clear when a change will impact usage, versus when a change can potentially be safely incorporated as an update. The first type of change will be referred to as a "major" change, and will require incrementing of the "major version number". The second type of change will be referred to as a "minor" change, and will only require incrementing of the "minor version number". And finally, the third type of change will be referred to as a "patch", and will only require incrementing the "patch version number".

Version numbers for CQL libraries can then be represented as:

<major>.<minor>.<patch>

For example:

library CMS146 version '1.0.0'

This would indicate the first major version of the CMS146 library. A minor change could be released by incrementing the minor version:

library CMS146 version '1.1.0'

And a major change could be released by incrementing the major version, and resetting the minor version:

library CMS146 version '2.0.0'

Minor changes are expected to retain backwards compatibility, but may introduce new features and functionality, while patch changes are expected to retain forward and backwards compatibility, and may only be used to fix issues.