Re: [netmod] yang versioning solution complexity and alternative approaches

[Jürgen Schönwälder <[e-mail]>]

Since I wrote this down anyway I can share it with the WG. Here is a
set of fictious examples adopting annotations as they are often used
in programming languages. The idea is to focus on documenting changes
instead of inventing fuzzy numbering systems plus magic algorithms to
find changes.

revision 2022-03-22 {  }
revision 2022-03-20 {  }
revision 2022-03-01 {  }

typedef foo {
  type int16;
  v:since "2022-03-22";
}

typedef bar {
  type int8;
  v:since "2022-03-20";
  status deprecated {
    v:since "2022-03-22"
    description "Deprecated, use typedef foo instead."
  }
}

typedef baz {
  type uint8;
  status obsolete {
    v:since 2022-03-20;
  }
}

typedef boo {
  type string;
  v:since 2022-03-01;
  v:incompatible {
    v:at "2022-03-20"
    description "Moved type from int8 to string.";
  }
  status "deprecated" {
    v:since 2022-03-22;
    description "This incompatible update was a bad idea.";
  }
}

/js

On Wed, Mar 09, 2022 at 11:16:09AM +0100, Jürgen Schönwälder wrote:
> Hi,
> 
> the YANG versioning solution appears to be complex.
> 
> - We introduce version numbers that smell a bit like SemVers but then
>   are not really SemVer.
> 
> - We have no solution to do meaningful things with these version
>   numbers, it does not even seem to be possible to decide whether
>   X.Y.Z derives from x.y.z or not. We still seem to believe that
>   having compatibility constraints embedded in module imports are a
>   workable solution even though we acknowledge future breaking
>   changes.
> 
> - We push for a reasonably complex algorithm to calculate deltas of
>   YANG module revisions to let users of modules to determine the real
>   impact of module updates on their work.
> 
> I wonder why we not consider the opposite approach, namely to have
> author making NBC changes to document them right where the changes
> are. If authors would write something like
> 
>       leaf foo {
> 	nbc-change "2022-03-01" {
>           description "changed type from int32 to string";
> 	};
> 	// ...
>       }
> 
> then tool and humans can easily figure out in which revision NBC
> changes occured and if they affect a certain usage of the module.
> 
> Instead of simply properly documenting the changes, we invent fuzzy
> version numbers and complex algorithms to reverse engineer the facts
> that could have easily been documented by whoever makes the change.
> 
> If the reason is that developers do not document their changes, then
> go and develop tools to force them to document their changes. I do not
> think it is fair to simply push the pain to the users of YANG modules.
> 
> /js
> 
> -- 
> Jürgen Schönwälder              Jacobs University Bremen gGmbH
> Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
> Fax:   [phone]         <https://www.jacobs-university.de/>

-- 
Jürgen Schönwälder              Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <https://www.jacobs-university.de/>