Software Engineers Have A Good Version Numbering System
Software projects large and small will often adopt what's known as "semantic versioning", which you can read about in-depth here, but let me reproduce the summary real quick so you don't have to stop reading this:Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible [interface] changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
While the VDW specs are not in fact a software product they do share a lot of similarities. Specifically,
- they change over time, and
- programmers rely on them to ensure compatibility of the code they write.
VDW Should Adapt This System
It seems to me this is a model we should adapt for our own uses. Specifically, and in the light of yesterday's Implementation Group meeting decisions:
The MAJOR version applies only to the set of specs in the aggregate. Individual table specs inherit the MAJOR version (which means they will sometimes change even when particular table specs have not changed).
A Proposed Adaptation
Reasons to increment the MAJOR version include:
- We have a large number of individual spec changes come through in a very short period of time + a concerted effort to implement them (a la the version 2 -> 3 changes).
- The number of un-coordinated spec changes have accumulated sufficiently in the judgment of the VDW Operations Committee Lead's opinion that the new major version is warranted.
Since MINOR and PATCH levels only apply at the individual table level, I would propose we increment the MINOR level for changes that will break existing code, or are otherwise important (again in the judgment of the VOC lead). For example:
- Change in the primary key.
- Addition or removal of one or more fields, or changing the name of a field.
- Significant expansion of the permissible values allowed for a field (for example the Virtual Care additions to the utilization specs)
- Change in a reference spec to which a field is tied (for example if we were to decide to update the language table to tie values from ISO 639-2 to ISO 639-3)
By contrast PATCH levels are incremented for less-important changes like:
- Edits to descriptions, either at the field or whole-table level
- Correcting obvious typos.
This will of course entail adding PATCH numbers to the existing table specs, but doing so will give us the freedom to note changes while at the same time distinguishing between more-important and less-important ones.
VOC Lead Makes The Call
Change proposal authors should feel free to suggest incrementing/not incrementing MINOR and PATCH levels if the proposal is adopted, but the ultimate decision should be made by the VOC lead.
What do you think--can this work? How would you decide to handle particular types of changes?
