Version 21.0 is current
Read the release notes for the current version.
The primary mission of HGVS Nomenclature is to facilitate reliable communication of sequence variants, which requires that the HGVS Nomenclature is stable. Nonetheless, modifications will be required from time to time in order to address new scientific needs, resolve inconsistencies, or clarify conventions. A key goal of the HVNC is to manage such changes in a way that balances the needs of progress and reliable data sharing, and to communicate the changes to the community clearly.
The HGVS Nomenclature uses concepts from Semantic Versioning to version releases.
Each release version will consist of 3 numbers separated by dots in the format
x.y.z with the following meanings:
- The major version (
x) will be incremented when changes are incompatible with existing conventions, and perhaps for other changes that are deemed to be significant. Major changes should be rare. Wherever possible, the HVNC will strive to ensure that incompatible differences between versions are likely to (or can be made to) result in obvious failures when implemented in software (e.g., failure to parse at all) rather than subtle errors that are difficult to catch or might be overlooked.
- The minor version (
y) will be incremented to indicate the addition of new features that are compatible with prior versions (with the same major version). For example, the adoption of a community proposal that adds support for a new variant type would trigger an increase in the minor version if the feature does not create conflicts with existing HGVS Nomenclature rules.
- The patch version (
z) will be incremented to indicate changes that fix or clarify the HGVS Nomenclature without changing the underlying intention. Patch edits will not change or extend the HGVS Nomenclature syntax.
Beginning January 2024 with version 21.0.0, version numbers do not correspond to dates
Historically, HGVS used date-based versions (e.g., 20.05 in May 2020). That practice has been discarded in factor of semantic versioning. Because versions should increase monotonically, the major release of HGVS Nomenclature in January 2024 will have major version 21. Beginning with version 21, users should not assume a correspondance between the major version and the year of release.
How should versions be used in practice?#
The HVNC will provide guidance about effective use of version numbers in future releases. For now, please use the following recommendations:
- Data providers (for example, databases, APIs, and manuscript authors) should state the version of HGVS Nomenclature that they use to communicate HGVS variant descriptions.
- Data consumers (especially software tools) should state the maximum version of HGVS Nomenclature that they can receive.
- For the purposes of predicting compatibility between providers and consumers, it suffices to compare HGVS Nomenclature major and minor version numbers as a floating point number. (The patch version is reserved for clarifications and minor changes that would be reasonably expected to have incidental consequence (at most) to the interpretation of HGVS variant descriptions.)
- Consider these cases:
consumer_version < provider_version(with same or different major versions): The most likely consequence is that the consumer will be missing features that are potentially used by the provider. The consumer may not be able to parse incoming data.
consumer_version = provider_version: This is the best case for reliable data exchange.
consumer_version > provider_version: If the major version numbers are equal, then the consumer would be expected to support all HGVS variant descriptions that might be generated by the provider. However, if the consumer major version is greater than the provider major version, caution should be exercised because the consumer is using a version of HGVS Nomenclature that has known and intended backward incompatibilities with earlier versions.