YANG Versioning Update

In a previous blog post (which I wrote about three years ago), I wrote about the consequences of adding version numbers to the YANG naming scheme. The take away message was that doing so has major consequences also for the protocols that are used to manipulate YANG defined data. Meanwhile, a concrete proposal has appeared to change the YANG versioning rules and to introduce semantic version numbers. Hence it is a good time to look at this topic again.

Background

The YANG data modeling language [RFC 7950] has a versioning model that rests on the following principle:

[…] changes to published modules are not allowed if they have any potential to cause interoperability problems between a client using an original specification and a server using an updated specification.

In July 2018, an individual document appeared collecting requirements for changing this principle to allow non-backwards compatible (NBC) changes. This work was triggered by a proposal to adopt semantic versioning rules. While the working group had mixed opinions on changing the current versioning model, a group of people started to develop a solution, which was eventually put to a first working group last call in February 2022. The last call again revealed a number of technical issues and it confirmed that the working group has mixed opinions on changing the versioning rules. A second working group last call was started in May 2023 based on revised documents. The second last call once again confirmed that there are mixed views on this work. Some people feel that the proposed solution does way more than necessary, that is it comes with unneeded complexity. Furthermore, it is incomplete concerning the details how backwards compatibility for deployed clients is provided, which is expensive if the YANG naming system is changed to include version numbers, as explained in my previous blog post on this topic.

Towards a Minimal Solution

As someone who was involved in the initial design of YANG, I was asked to explain where I stand and what I believe a minimal solution could look like. My position rests on the following thoughts:

  • Changes to the semantics of the YANG language (excluding bug fixes) require bumping the version of the language. There are many ways to bump the version of the language, some more heavy weight than others. A light weight solution would be a relatively small RFC making updates to RFC 7950. RFC 7950 together with these updates could then define YANG 1.2. Revising RFC 7950 itself is a heavy weight solution since it is a 200+ pages specification and it is both tempting to make additional changes (which may result in a multi-year project) and it is risky to introduce bugs that did not exist before.

  • There is a difference between bug fixes and other NBC changes, e.g., to fix module design flaws. The line between them is at times a judgment call. It remains unclear whether the goal of the work is to better deal with (ideally) rare bug fixes (and this may include alignment of YANG definitions to changes of other specifications) or whether the purpose is to significantly increase the rate of NBC changes by adopting a more agile ‘publish quickly and fix later even if it breaks things’ development model. To preserve interoperability, I believe a conservative approach that allows NBC changes only in exceptional situations should be followed.

  • Version number triples are used widely but projects frequently do not follow the semantic versioning rules strictly. It is often a judgment call whether a change requires to bump the major or minor version number or whether a change is considered a bug fix. While I see value in communicating the amount of change in a version number triple, I do not believe that semantic versioning rules are practical if applied strictly.

  • NBC changes deserve to be documented where they occur. It is then easy for programs to derive summary information. The proposal on the table has this backwards by declaring summary information at the module level and suggesting some tooling to be used to find what actually changed (which will fail on semantic changes buried in description statements). In my view, it is much more desirable to document meta information, such as in which version definitions were added, obsoleted, deprecated or semantically changed (if we allow that), by tagging the affected definitions. Right now the best we have is free-form text in description statements of revision statements, which does not enable tools to do even simple things like determining whether changes affect an importing module.

  • I believe that not breaking deployed code whenever feasible must remain the guiding principle. Introducing new definitions or entire new modules instead of altering existing definitions enables gradual adoption. Sure, in a closed world situation, this may not matter, but if we believe in open interfaces, then not breaking deployed code has to be taken seriously.

Conclusions

A minimal solution fixes YANG’s import by (strict) revision mechanism (by introducing an import by minimum revision) and it provides annotations to document changes (additions, status changes, semantic changes) where they occur. This can be achieved by writing a relatively short RFC updating RFC 7950. Such a minimal solution addresses most if not all of the requirements stated in the requirements document.

I have no problem if people want to decorate YANG modules with additional version number triples. But I do not think that version number triples can break the general principle that backwards compatibility must be maintained whenever feasibly. Proposals that effectively add a version number to YANG’s naming scheme have substantial costs since they also affect the protocols used to manipulate YANG defined data, as explained in my previous blog post on this topic. Hence, such a project would require significant effort and surely requires a major version update of the YANG specification and the associated protocols.