Added some text in the section on guidelines to YANG model authors

netmod-wg · Jan 17, 2019 · 2bccc64 · 2bccc64
1 parent 314c60d
commit 2bccc64
Showing 1 changed file with 17 additions and 0 deletions.
diff --git a/yang-semver/draft-verdt-netmod-yang-semver.xml b/yang-semver/draft-verdt-netmod-yang-semver.xml
@@ -473,6 +473,7 @@ leaf imperial-temperature {
 
 <section anchor="guidelines" title="Guidelines">
    <section anchor="guidelines_authors" title="Guidelines to YANG model authors">
+      <section anchor="authors_semver" title="Use of semantic versioning">
       <t>From a published revision N of a module, the next published revision N+1 of the module SHOULD
          have one of:
          <list style="numbers">
@@ -500,6 +501,22 @@ leaf imperial-temperature {
       <t>As explained in <xref target="implementation_experience"/>, while programatically determining a semantic version is possible
          using the pyang utility, human overisght is highly recommended because of some special cases which can not be detected by pyang.
          Therefore, a model author SHOULD use both means to determine a model's semantic version.</t>
+       </section>
+       <section title="Making non-backwards-compatible changes to a YANG module">
+       <t>There are various valid situations where a YANG module has to be modified in a non-backwards-compatible way, such changes SHOULD be done gradually. Here are some examples and guidelines on how the changes should be made:
+         <list style="symbols">
+            <t>Removing a node from the data tree, e.g. because support for the corresponding feature is being removed: 
+            <list style="numbers">
+               <t>The node's status SHOULD be changed to "deprecated" and it MUST be supported for a mandatory amount of time acceptable to the consumers of the YANG model. This is a backwards-compatible change.</t>
+               <t>When the mandatory amount of time has passed, the node's status MAY be changed to "obsolete" and it is not supported anymore. This is a non-backwards-compatible change.</t>
+            </list>
+            </t>
+            <t>Changing the type of a leaf-node</t>
+            <t>Reducing the range of a leaf node</t>
+            <t>Changing the key of a list</t>
+         </list>
+       </t>
+       </section>
    </section>
    <section anchor="guidelines_clients" title="Guidelines to YANG model clients">
    </section>