OpenConfig Release Versioning
Background and Motivation
While each individual OpenConfig model can be tagged with a semantic version
(see semver.md), models are often interdependent, or need to be
used together, for example when managing a full device. It is therefore useful
to define OpenConfig “releases” that contain a set of models that are designed
to work together. This also enables tracking breaking changes at the repository
level, as well as allowing public users to view and download tagged collections
of self-consistent models (see also the description of
In light of the above, this proposal introduces tagging
semantic versions to the set of all OpenConfig models as
a whole along with some OpenConfig-specific guidelines. Each release is
therefore the cumulative set of models committed to the master branch at a
certain point in time, and is tied to a specific commit in the OpenConfig
repository. YANG validators ensure that each release consists of collection of
published OpenConfig models that work together: that is, interdependencies
(e.g., imports, augments) and cross-references (e.g., leafrefs) are all
As a side note, these releases are compatible with the notion of
YANG release bundles.
A regular release of https://github.com/openconfig/public containing a set
of compatible models (consisting of the entire set of models within the
openconfig/publicrepo) is created roughly every quarter. The tag is
semantic versioning rules. A major, minor, or patch
version increment is possible at each release, although non-backward
compatible releases SHOULD be released at a less-frequent cadence.
At the current time, releases are only expected to occur at the HEAD branch
of the repository, meaning patch releases for non-HEAD model versions are
not expected to be made.
Non-backward compatible model changes affecting a feature that has
reasonable functional test coverage (via
or implemented on a device SHOULD be made infrequently. The OpenConfig
working group will create non-backward compatible releases periodically by
considering both velocity and maintenance cost implications.
e.g. It is November 2022, and the current latest release of OpenConfig
v2.3.1. The OpenConfig community decides to change the default
value of the leaf path
/interfaces/interface/config/enabled. This is a
breaking change since it would cause featureprofile tests that test for the
behaviour of the default value without explicitly setting this leaf to begin
to fail. As a result, the pull request for this change is not merged until
the end of the quarter in December. In January 2023, a new release is
v3.0.0containing this update.
Any non-backward compatible change for a pre-
v1.0.0YANG module does NOT
by itself necessitate a major revision change for the overall models
Patch releases may be created at any time
for backward compatible bug fixes, or equivalently, where only patch number
increases occurred in models.
Pre-releases may be created at anytime to
quickly introduce new changes to the models. These are not intended to be
long-term, stable releases – they should be replaced with the next regular
release that encompasses these changes as soon as it becomes available.
Wherever possible, it is RECOMMENDED to make backward compatible API changes
(e.g. deprecating leaves via the
for at least one minor release prior to a non-backward compatible API change
in order to ease the transition to the new API. These leaves are then
expected to be removed or modified in the next major version release. NOTE:
This guideline may change once OpenConfig operators gain more experience
managing breaking changes.
Release documentation should include the list of models and their version
numbers contained in the corresponding release.
v1.2.0) MAY be given a name for easier human
identification, e.g. “September 2022”. A client can thus assert they are
compatible with the “September 2022” release of OpenConfig. It’s expected that
vendors will have some deviations and augments from the baseline; further, some
vendors may offer the ability to configure their NOS (network operating system)
to support different releases of https://github.com/openconfig/public.
Note that 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
For non-backward compatible changes involving changing the type of a leaf, the
new leaf SHOULD have a different name than the previous leaf.