Semantic versioning for OpenConfig models

Semantic Versioning for OpenConfig models

contributors: Anees Shaikh, Josh George, Rob Shakir, Kristian Larsson
September 27, 2015

Background and motivation

This document proposes to adopt Semantic Versioning (semver) for published OpenConfig YANG models in the same way that software projects use similar versioning schemes to indicate the maturity and compatibility of software as it evolves. Semver bases its versioning on an API contract with developers and users. The basic format of a semver number is XX.YY.ZZ-release where XX is the major version number, YY is the minor version number, and ZZ is a patch level. Additional information can be optionally provided with a suffix. Detailed specification on the semver versioning rules are available at the link above. Any non backward-compatible change to the API requires incrementing the major version number, while feature changes that do not break clients are indicated by incrementing the minor version number. Non-feature patches that are backward compatible are indicated with an increment to the patch number.

Semantic versioning is proposed as an addition to YANG revision statements for a number of reasons:

This is simply not practical (and is largely motivated by SNMP MIB notions). YANG models are not mature (less than 5 models have been made IETF RFCs and these are not implemented by any major device platform). Server and client implementations are only now being developed and deployed and significantly more operational experience is needed before APIs can be frozen.

Semantic versioning has its own issues and it may be that in OpenConfig we will have to adapt the specification somewhat based on considerations for versioning YANG models. Also semver does not address the problem of how to version groups of interdependent modules (e.g., a device model composed of many constituent models).

Note that we would continue to use revision statements, e.g., with a date set to the day a new semantic version is published. This allows consumers to continue to use current YANG constructs such as import by revision.

General guidelines for versioning OpenConfig YANG modules

An immediate question that arises when considering how to version YANG modules is what criteria should be used to judge that a module is mature enough that an API contract should be established with a version number.

According to the semver specification, software that is pre-release with major version 0 may break clients as long as the major version number remains < 1. That is, with major version 0, there should be no expectation of compatibility from one release to another, even if only the minor version number is changing.

Based on these considerations, the following basic guidelines are proposed for versioning OpenConfig modules:

API changes in YANG modules

For the purposes of semver, the API presented by a YANG model consists of it’s data nodes and corresponding paths. Other elements of the model may not, strictly speaking, be considered part of the API, but still could have significant impact on the use of the model by developers or clients. Such elements include default values, configurability of a node, and behavior of a given data node (as described by the description statement).

Since the API of the YANG module is a combination of these explicit and implicit elements, the criteria for determining when a revision requires a major number increment is not always straightforward. Below we list some general rules for determining the API has changed, and consequently would increment the major version number.

Proposed version number of current OpenConfig models

The table below lists the currently published OpenConfig models, and a proposed semver number based on releases so far (see the notes column).

As of September 27, 2015
Model (YANG modules) Proposed version number Notes
BGP
openconfig-bgp openconfig-bgp-multiprotocol openconfig-bgp-operational openconfig-bgp-policy
1.0 or 1.1 5 earlier revisions - 0.1 to 0.5move to 1.0 since now being implemented by vendors (1.1 with name change to openconfig-bgp*)
routing policy
openconfig-routing-policy
1.0 or 1.1 3 earlier revisions 0.1 to 0.3move to 1.0 since now being implemented by vendors (1.1 with name change to openconfig-*)
local routing
local-routing
0.1.3 1 initial version followed by 3 minor text fixes implementations pending
openconfig-types 0.1 1 initial version
MPLS
mpls mpls-types mpls-igp mpls-ldp mpls-sr mpls-rsvp mpls-te mpls-static
0.2 2 published revisions
optical transport
openconfig-terminal-device openconfig-transport-types
0.1 1 initial version
interfaces + vlan
openconfig-interfaces openconfig-if-ethernet openconfig-if-aggregate openconfig-if-ip openconfig-vlan
0.1 1 initial version
RIB
openconfig-rib-bgp openconfig-rib-bgp-ext
0.1 not yet published
Telemetry configuration
openconfig-telemetry
0.1 not yet published
Inventory
openconfig-inventory
0.1 not yet published

Versioning bundle releases

While each individual OpenConfig model can be tagged with a semantic version, models are often interdependent, or need to be used together, for example to manage a full device. It is therefore useful to define OpenConfig ‘releases’ that contain a number of models that are designed (and confirmed) to work together. Release tagging also makes it convenient for public users to view and download a collection of self-consistent models (see also the description of GitHub releases).

Proposed guidelines for versioning and managing bundle releases include:

Notwithstanding the policies for incrementing the release version, release version numbers need not be a function of individual model release numbers (e.g., the max version number of all of the models in the release).

These policies may not apply when the release major version is 0 (see below).

Initializing the release version number

Since individual OpenConfig models are at different stages of maturity, and will remain so for some time, there seems to be several options for bootstrapping the release version.

One option is to use a major version 0 until all of the individual models reach major version number >= 1. This would likely keep the release version at 0 for a long time, however, since new models are published often. A variant of this option could be to designate a subset of models as ‘primary models’ and transition the release to version >=1 when all of the primary models have reached version >= 1.

Another possibility is to bootstrap the release version as 1.0, given that two individual models have reached version >= 1 (BGP and routing policy).