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
GitHub releases).

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
resolved.

As a side note, these releases are compatible with the notion of
YANG release bundles.

Policy

Basic Guidelines

1. 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/public repo) is created roughly every quarter. The tag is
   named vx.y.z (e.g. v1.2.0) following
   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.

2. Non-backward compatible model changes affecting a feature that has
   reasonable functional test coverage (via
   OpenConfig featureprofiles)
   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
   models is 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
   created, versioned v3.0.0 containing this update.

3. Any non-backward compatible change for a pre-v1.0.0 YANG module does NOT
   by itself necessitate a major revision change for the overall models
   repository.

4. Patch releases may be created at any time
   for backward compatible bug fixes, or equivalently, where only patch number
   increases occurred in models.

5. 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.

6. Wherever possible, it is RECOMMENDED to make backward compatible API changes
   (e.g. deprecating leaves via the
   status statement)
   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.

7. Release documentation should include the list of models and their version
   numbers contained in the corresponding release.

Each release vx.y.z (e.g. 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
release).

Corner-Case Guidelines

For non-backward compatible changes involving changing the type of a leaf, the
new leaf SHOULD have a different name than the previous leaf.