On 6/8/22 13:29, Andy Bierman wrote:
On Wed, Jun 8, 2022 at 10:04 AM Jürgen Schönwälder <[email protected]<mailto:[email protected]>> wrote: On Wed, Jun 08, 2022 at 04:40:05PM +0000, Rob Wilton (rwilton) wrote: > > > > Rob, > > > > discussing details is likely distracting from the main difference in > > our viewpoints so I will only give a top posting response. > > Okay. > > I believe that the consensus of the authors on the weekly calls is also that > annotations at the "data definition" level are helpful, alongside module and > package (i.e., schema level) version numbers. > > Hence, my understanding of the main difference is whether > non-backwards-compatible changes MUST always be explicitly documented at the > data node level (and hence whether that means that data nodes can never be > deleted from a YANG module), or whether these annotations are unnecessary, > and potentially unhelpfully clutter the YANG module in the cases where > tooling can robustly infer whether the change is backwards compatible or not. For me, its a MUST. If you potentially break things, you have to tell others. If you choose to violate the YANG 1.1 update rules, you have to document that. Deleting data nodes (well, data nodes is actually too limiting but that is likely a detail) is a special case and some way to document that something was remvoed is indeed needed. I think it is wrong to use a corner case to design the general case here. Strongly agree with all of Juergen's concerns. It is normal engineering practice to identify API changes in the documentation for a specific API (not at some global level). I agree that it is normal to reflect API changes. Typically I see them in release notes. In my experience, I have seen Java track certain data like "first introduced in" in classes and methods themselves. There is also precedent for a global, API-level indication of NBC changes, and that is the REST API paradigm of a version component to the URI (e.g., /api/v2/RESOURCE). The interactions between YANG modules are too complex for a "module-is-NBC" flag to really help. The packages work aims to address this interaction using the same labeling at more of a holistic API level. Joe IMO only NBC changes are a MUST. BC changes are a MAY. These changes should not be documented in an extension that MAY be ignored. The existing description-stmt is mandatory-to-implement for all tools. Andy If your YANG module gets cluttered because of NBC changes, perhaps there is something to be said about the engineering process. To unclutter a module, you give it a new new and remove the history. I do not believe that there is a robust algorithm to infer in the general case whether a change in NBC or not, so it is pointless to consider this option. > Possibly there is also a second difference of opinion as to whether it is > appropriate/safe to assume that any changes that are not explicitly marked as > being non-backwards-compatible are in fact backwards compatible. I.e., > specifically, is a "backwards-compatible" annotation also required in the > cases where a tool cannot safely infer that a change is backwards-compatible. If NBC markers are a MUST, then everything not marked is a BC change. In YANG 1.1, everything following the update rules is a BC change, hence there are no markers. It seems logical to me to keep the existing assumptions. > Do you think that accurately represents the difference in opinion > from your perspective? There is another one concerning the implementation. If YANG is changed in such a way that existing deployed tools derive wrong conclusions, then this is an NBC change to YANG and the YANG version number needs to be incremented. /js -- Jürgen Schönwälder Jacobs University Bremen gGmbH Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany Fax: +49 421 200 3103 <https://www.jacobs-university.de/> _______________________________________________ netmod mailing list [email protected]<mailto:[email protected]> https://www.ietf.org/mailman/listinfo/netmod
_______________________________________________ netmod mailing list [email protected] https://www.ietf.org/mailman/listinfo/netmod
