Formally defining backwards compatibility for YANG extensions

[BalazsLengyel]

When trying to determine whether a module update is compatible or not all YANG statement changes need to be considered. Compatibility aspects of YANG extension statements are not know as each extension is unique and its semantics are described only in a description statement using plain English. While that might be sufficient for an expert human reader, it is not usable in a SW algorithm.

There is a need to define whether changing specific YANG extension statements is backwards compatible or not. This should be defined in a formal, machine readable manner.

[BalazsLengyel]

A possible formal definition of extension backwards compatibility could be the following:

extension extension-backward-compatibility {
description
"Describes if an update to a statement using the YANG extension
defined by the parent statement to this extension is considered
backwards compatible or not.

  The statement MUST only be a substatement of the extension
  statement used to define a new statement within the YANG language.
   
  Zero or One extension-backward-compatibility statement per 
  extension statement is allowed. 
  No substatements are allowed.

  The argument shall follow the following YANG definition:
   
  leaf nbc-changes {
    type bits {
      bit add {
        description 
         "Adding this extension statement is a 
         backwards incompatible change";
      }
      bit remove {
        description 
         "Removing this extension statement is a 
         backwards incompatible change";
      }
      bit change {
        description 
         "Changing this extension statement is a 
         backwards incompatible change";
      }
    default '';
  } 
  
  If the argument is not present all changes to the usage of the 
  parent extension statement are backwards compatible.
  If the argument is present changes listed in the argument 
  are not backwards compatible while changes not listed are 
  backwards compatible.";
  
argument nbc-changes;

}

[jsterne]

Minor nit - let's use the "non backwards compatible" terminology like we did in other drafts (instead of 'incompatible).

[jsterne]

One aspect that might not be covered by these 3 bits: what about extensions that depending how they change, it could be BC or NBC ? e.g. imagine the YANG 'range' statement didn't exist and someone invented it as an extension. Increasing the range is BC but shrinking it is NBC.

[rgwilton]

Do we want to be able to annotate as extension as being editorial only?

Perhaps the tooling may categorize into a finer set of categories (e.g. nbc, bc, editorial, potential-nbc) and then those categories are combined into the actual versioning number, depending on the versioning scheme.

Where does the draft pull the definition from editorial from? Probably can just reference the definition in the Semver draft without requiring Semver.

[BalazsLengyel]

IMHO we don't want to go into to details like: one type of change is BC while the other type is NBC. To detailed, to lenghty.

Do we need editorial-change marking too? -IMHO not sure, but if e follow semver maybe it is a good idea.

Do we need a potential-nbc output too? - Looks like a good idea.

[BalazsLengyel]

Definition ver-2:

extension extension-backward-compatibility {
description
"Describes if an update to a statement using the YANG extension
defined by the parent statement to this extension is considered
backwards compatible or not or only editorial.

  The statement MUST only be a substatement of the extension
  statement used to define a new statement within the YANG language.

  Zero or One extension-backward-compatibility statement per 
  extension statement is allowed. 
  No substatements are allowed.

  The mandatory argument SHALL contain 3 comma separated strings. 
  Each string defines what kind of change the adding, changing and 
  deleting of the extension represents (in the above order). 
  Each substring SHALL follow the following YANG definition:
  
  typedef change-type {
    type enumeration {
      enum nbc {
        description "Non-backwards compatible change";
      }
      enum potentially-nbc {
        description "A change that maybe either non-backwards  
          or backwards compatible";
      }
      enum bc {
        description "Backwards compatible change";
      }
      enum editorial {
        description "Editorial change";
      }
    }
  }
        
  E.g., the following indicates that adding the extension is 
  bc, changing it is editorial but removing it is potentially 
  non-backwards compatible.
  
  "bc,editorial,potentially-nbc"
  ";

argument change-types;
}