Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis

Xufeng Liu <xufeng.liu.ietf@gmail.com> Wed, 06 March 2024 01:26 UTC

Return-Path: <xufeng.liu.ietf@gmail.com>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 0C76EC14CF1D for <netmod@ietfa.amsl.com>; Tue, 5 Mar 2024 17:26:17 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -6.094
X-Spam-Level:
X-Spam-Status: No, score=-6.094 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, MANY_SPAN_IN_TEXT=1, RCVD_IN_DNSWL_HI=-5, RCVD_IN_ZEN_BLOCKED_OPENDNS=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_REMOTE_IMAGE=0.01, T_SCC_BODY_TEXT_LINE=-0.01, URIBL_BLOCKED=0.001, URIBL_DBL_BLOCKED_OPENDNS=0.001, URIBL_ZEN_BLOCKED_OPENDNS=0.001] autolearn=unavailable autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com
Received: from mail.ietf.org ([50.223.129.194]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Jir0ssOGzrc6 for <netmod@ietfa.amsl.com>; Tue, 5 Mar 2024 17:26:12 -0800 (PST)
Received: from mail-lf1-x133.google.com (mail-lf1-x133.google.com [IPv6:2a00:1450:4864:20::133]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3556FC14F6BD for <netmod@ietf.org>; Tue, 5 Mar 2024 17:26:12 -0800 (PST)
Received: by mail-lf1-x133.google.com with SMTP id 2adb3069b0e04-5131bec457eso298652e87.0 for <netmod@ietf.org>; Tue, 05 Mar 2024 17:26:12 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709688370; x=1710293170; darn=ietf.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=onlWY+jHOmZ6wToIVmA7ToK8B9RyBblry6mnYCP/FYs=; b=KrZqqhFjA9faKHsRr70uoC6INiclfS3lFq4wP6vBFeBQbeduQvPB/WJp+Jrok1UvHb 1PEb7nGp3D5gFyWkac1KWQBaacE3t/joWXMnpi9YAARqUi91WRzHGgK36/XChr8Vjk4E x6yQ3IfYNpcuGCyAc2fYCD4gJrlugoI+DLVQdy2sE9IwKhzINnWfWtC4RPKI8a7+PDSv PZtcck2z+I2od5i98I5whWg69NpJgjs1LKQ7o9z3YkPKP79dmwyuxxSSRUdhlEVHI1xt Dc2KIn3ufHD01aqEV/JA3TW5ZFq43IDGq/pE8y7sn8qt8/pyFKjd/zozKTp8sxgBmDCw uYBQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709688370; x=1710293170; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=onlWY+jHOmZ6wToIVmA7ToK8B9RyBblry6mnYCP/FYs=; b=hfLcCNNAmn0uT+OJ2jvEMFCZfqrmjB/OzARMLlo5bv2g2jpONPja1otFf0+HtOok7r Jnl3xr+ISwWUCsOBoXUR43EoQbWJ9gQ7gaGjb5LeP3YcKADFKhIEMyihDbrsFnRZFeZ2 Vp0hCkH10ZHPD5xENFVvhircusvykcKKB2K/TkmiJdykXy7h9UcaBOhbqGNSK5HWTTxH LRK2g3SBt/fC6Ex9GeejDJITY1oSHlLdCWNna6Ja9rJo0tvzOIpn0NamVGCsvRSImbMs 4Jpi/ksuFC30+41+1SHr0/IeW6UtsrTA7bUutnc358+SVU9ZqecKjYEq5eZFjhFh2mLV dc0Q==
X-Forwarded-Encrypted: i=1; AJvYcCUUYBaI7WThtv+HM+wQzafBcaiBEtSFgXwF2hRxIgBWcXsxKxsREUdYrPjMne7Mh9BIYEPJ1q2An5cbVHpYaqs=
X-Gm-Message-State: AOJu0Yw2aBFCe7yNqrr+8gY0y36+mK73a62ishimAkXARRYZ1DNToAar DUaR/6WMYf2XQHbyUig5zRoKF9ktz27YVzcpB1EpXN3codH5n6Eyr3Lm0fNGvWZMuFjYCNKM/8v WZLUOmnnGLhP1JoM/fwerQWRkM8VlUPZd9no=
X-Google-Smtp-Source: AGHT+IELMq/cyBraptXKix/4+3AQRlzry7uqG902SgZ5tYSnnLyF/f+c57V2Jx/rK3Sp784zJV6q5idU9It3G39g/TA=
X-Received: by 2002:a19:e017:0:b0:513:4891:d086 with SMTP id x23-20020a19e017000000b005134891d086mr1168570lfg.17.1709688369291; Tue, 05 Mar 2024 17:26:09 -0800 (PST)
MIME-Version: 1.0
References: <8a9d527a81db4ec9b9fc396691346fad@huawei.com> <5c0d327d90b14b0f88cae8f610b20727@huawei.com> <DU2PR02MB1016007175B46DB55BF97050688222@DU2PR02MB10160.eurprd02.prod.outlook.com> <0100018e0f2298ba-452d56e0-9568-4ef0-8cb9-70dbcd2efff3-000000@email.amazonses.com> <6933a4c30e864e5a9c488e501751e9ef@huawei.com> <0100018e103189dd-e9d89c4c-c2cf-4a6a-b7f8-361bed63d9eb-000000@email.amazonses.com> <CABCOCHSQ_ssh-q6YwnPT1HCfnkrtNPJaupW-otRAvnXygU9+EA@mail.gmail.com>
In-Reply-To: <CABCOCHSQ_ssh-q6YwnPT1HCfnkrtNPJaupW-otRAvnXygU9+EA@mail.gmail.com>
From: Xufeng Liu <xufeng.liu.ietf@gmail.com>
Date: Tue, 05 Mar 2024 20:25:57 -0500
Message-ID: <CAEz6PPQuYM1+DpvE_97bAZ0BCC++nFDoben=nQY4YyJXo54bQw@mail.gmail.com>
To: Andy Bierman <andy@yumaworks.com>
Cc: Kent Watsen <kent+ietf@watsen.net>, Italo Busi <Italo.Busi=40huawei.com@dmarc.ietf.org>, "netmod@ietf.org" <netmod@ietf.org>
Content-Type: multipart/alternative; boundary="000000000000edaa950612f3d7ea"
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/0Q0YiyNi15V-Szzf5awLVh-15_c>
Subject: Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.39
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 06 Mar 2024 01:26:17 -0000

Hi Med and all,

Sorry that I would not agree with the proposed text, especially the
following:

   "If the complete

   tree diagram is too long (more than 5 pages, typically) even with

   groupings unexpanded (Section 2.2 of [RFC8340]), the authors SHOULD

   NOT include it in the document.  A stable pointer to retrieve the

   full tree MAY be included."

I agree with Chris, Italto, and Andy on the usefulness of the full,
complete YANG trees presented in the document.


A tree provided by a "stable pointer" is not a complete substitute for the
tree embedded in the document:

1) A "stable pointer" site (such as the YANG Catalog) builds the tree with
different versions of dependencies (usually the latest versions at the time
of browsing), while the embedded tree view is built with the versions of
dependencies available at the time when the document is published. The
embedded tree view provides the context of the model design at that
particular point in time.

2) A "stable pointer" site (such as the YANG Catalog) may present the tree
in a format different from RFC8340. In many use cases, it is useful and
convenient to browse the tree in collapsable and clickable web pages, but
in other cases when we want to have a plain-text tree (or a portion of the
tree) in the RFC8340 format, it is not convenient to use such a web site.

In addition, I am not convinced by the following:

      "The full tree diagram of the module can be generated using,

      e.g., the "pyang" tool. That tree is not included here because

      it is too long."

For casual readers setting up "pyang" is not a convenient way to consume
the document, especially when the YANG module has many imported
dependencies. It would be even harder to reproduce the tree snapshot
reflecting the point in time when the document was published.

Having a similar experience as Italo described, I would prefer:
1) Every document includes a full, complete tree view;
2) If the tree view is long, it can be put in an appendix;
3) If the tree view contains naturally separated pieces (such as separate
augmentation trees), the lossless tree pieces can be put into subsections
of the document.

Thanks,
- Xufeng

<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
Virus-free.www.avast.com
<https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail>
<#m_-9098914578306838048_DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

On Tue, Mar 5, 2024 at 5:08 PM Andy Bierman <andy@yumaworks.com> wrote:

>
>
> On Tue, Mar 5, 2024 at 1:47 PM Kent Watsen <kent+ietf@watsen.net> wrote:
>
>> In addition to improving IETF-published artifacts, it would be nice if
>> there were a module-browser that acted a little bit like an IDE, jumping to
>> where in other modules imported bits are defined.  Perhaps in
>> NetconfCentral or YANG Catalog.  This jumping behavior could exist in both
>> the text and tree-diagram views.
>>
>>
>
> I like the plain-text full tree diagram that is usually present before the
> YANG module.
> Often the groupings and typedefs are from external modules, and/or are
> difficult to figure out.
> Yet the groupings and typedefs must be found and read to understand the
> model.
>
> It would be nice if the HTML version of the draft/RFC had links in the
> tree diagram to the actual YANG statements.
>
> DRY vs. WET: the structure of a YANG module (i.e. dividing into sections)
> is too complex have strict rules.
> A tree diagram for the definitions relevant to each section is usually
> helpful, in addition to the full tree diagram.
> I would avoid SHOULD and SHOULD NOT for this issue.
>
>
>
>> K.
>>
>
> Andy
>
>
>>
>>
>> On Mar 5, 2024, at 11:21 AM, Italo Busi <Italo.Busi=
>> 40huawei.com@dmarc.ietf.org> wrote:
>>
>> I like the idea of relying on tooling with hyperlinks
>>
>>
>>
>> For txt and pdf, I agree that a link is the best option since these
>> formats are not optimized for including YANG trees
>>
>> Italo
>>
>>
>>
>> *From:* Kent Watsen <kent@watsen.net>
>> *Sent:* martedì 5 marzo 2024 16:02
>> *To:* mohamed.boucadair@orange.com
>> *Cc:* Italo Busi <Italo.Busi@huawei.com>; Qin Wu <bill.wu@huawei.com>;
>> Mahesh Jethanandani <mjethanandani@gmail.com>; netmod@ietf.org
>> *Subject:* Re: [netmod] Long trees RE: Next steps for
>> draft-ietf-netmod-rfc8407bis
>>
>>
>>
>>
>>
>> It seems that there are two camps:
>>
>>
>>
>>             1) those that want the tree-diagrams to be as DRY as possible
>>
>>             2) those that want the tree-diagrams to be as WET as possible
>>
>>
>>
>>                           DRY = Don't Repeat Yourself
>>
>>                           WET = Write Every Time
>>
>>
>>
>> Tooling can help both cases.
>>
>>
>>
>> For (1), the tree-diagrams are unexpanded, but surrounding text should
>> point to where each used-grouping is defined.   The better tooling-assisted
>> approach, is for the used groupings *inside the tree-diagram” to become
>> hyperlinks (only possible in supporting formats).   Extending this idea
>> further, hyperlinks could be provided for typedefs and identities too.
>>
>>
>>
>> For (2), for plain-text and PDF formats, a link to where the image can be
>> accessed would be nice.  For the HTML format, inlining the complete
>> (unfolded) tree-diagram with horizontal-scrolling would be ideal.
>>
>>
>>
>> Kent
>>
>>
>>
>>
>>
>> On Mar 5, 2024, at 3:01 AM, mohamed.boucadair@orange.com wrote:
>>
>>
>>
>> Hi Italo,
>>
>>
>>
>> Thanks for sharing your thoughts.
>>
>>
>>
>> Please see inline.
>>
>>
>>
>> Cheers,
>>
>> Med
>>
>>
>>
>> *De :* Italo Busi <Italo.Busi@huawei.com>
>> *Envoyé :* lundi 4 mars 2024 19:38
>> *À :* Qin Wu <bill.wu@huawei.com>; Mahesh Jethanandani <
>> mjethanandani@gmail.com>; BOUCADAIR Mohamed INNOV/NET <
>> mohamed.boucadair@orange.com>
>> *Cc :* netmod@ietf.org
>> *Objet :* RE: [netmod] Long trees RE: Next steps for
>> draft-ietf-netmod-rfc8407bis
>>
>>
>>
>> Hi Med,
>>
>>
>>
>> In my personal experience, I have found the YANG tree included in the
>> IETF RFCs/I-Ds useful only when they are complete, even if they are too long
>>
>> *[Med] I agree that having readily available full trees is useful,
>> however the question is whether it should be embedded in the RFC text or
>> would having stable links to access such trees be much more convenient?
>> Note also that when the tree is too long, there are better places to
>> display them for better user experience (control views, etc.), which we
>> don’t have with the txt version.*
>>
>>
>>
>> In RFC8795 you can find an example of a too-long YANG tree which I am
>> using quite often
>>
>>
>>
>> *[Med] If the Datatracker includes a link to the tree or 8795 includes a
>> stable pointer to the full tree without the editing limitations of IETF
>> docs, the experience would be the same, if not better. No?*
>>
>>
>>
>>
>>
>> I have found YANG trees with unexpanded grouping almost impossible to
>> use. In draft-ietf-teas-yang-te you can find an example of a YANG tree with
>> unexpanded grouping which I am not using at all. In this case, I refer to
>> the YANG catalog to get the complete tree
>>
>>
>>
>> *[Med] ACK.*
>>
>>
>>
>> I have also found the YANG tree pieces almost useless (even if much
>> better than the YANG trees with unexpanded grouping) without some overview.
>>
>>
>>
>> *[Med] Not having an overview to describe the overall structure and help
>> readers navigate among all the various levels is a bug of these specs, IMO.
>> The narrative part of the spec is supposed to help readers digest the
>> structure and zoom in/out when diving into specifics. I think that we need
>> collectively to better explain the rationale of a module design and
>> articulating the various parts of a module. The use of subtrees for too
>> long trees is a means to help structure the description sections.*
>>
>>
>>
>> RFC8348 is an example of YANG tree pieces which I am using very rarely.
>> In most of the cases, I refer to the YANG catalog to get the complete tree
>>
>> *[Med] ACK.*
>>
>>
>>
>> I am wondering whether the issue of YANG tree too-long could be resolved
>> by updating the IETF tooling. For example, I have noted that the html-ized
>> version of the I-Ds is now working well with artwork exceeding the 72
>> characters limit …
>>
>>
>>
>> Maybe the html or html-ized version of the I-D/RFC might include the
>> jstree pyang output instead of the tree pyang output
>>
>>
>>
>> *[Med] Fully agree that tooling is the way to go here. Having a stable
>> pointer to the tree (including displaying it from the Datatracker metadata)
>> would achieve that objective.*
>>
>>
>>
>> *Back to the txt version, here is an updated version of the reco (for
>> further discussion):*
>>
>>
>>
>> ==
>>
>> NEW:
>>
>>    YANG tree diagrams provide a concise representation of a YANG module
>>
>>    and SHOULD be included to help readers understand YANG module
>>
>>    structure.  If the complete tree diagram for a module becomes long
>>
>>    (more than 2 pages, typically), the diagram SHOULD be split into
>>
>>    several smaller diagrams (a.k.a subtrees).  For the reader's
>>
>>    convenience, a subtree should fit within a page.  If the complete
>>
>>    tree diagram is too long (more than 5 pages, typically) even with
>>
>>    groupings unexpanded (Section 2.2 of [RFC8340]), the authors SHOULD
>>
>>    NOT include it in the document.  A stable pointer to retrieve the
>>
>>    full tree MAY be included.
>>
>>
>>
>>    The document SHOULD include the following note if the full tree is
>>
>>    not included:
>>
>>
>>
>>       -- If no stable pointer to retrieve the tree is included
>>
>>
>>
>>       The full tree diagram of the module can be generated using,
>>
>>       e.g., the "pyang" tool. That tree is not included here because
>>
>>       it is too long (Section 3.4 of [RFCXXXX]). Instead, subtrees
>>
>>       are provided for the reader's convenience.
>>
>>
>>
>>       -- If a stable pointer to retrieve the tree is included
>>
>>
>>
>>       The full tree diagram of the module can be retrieved at
>>
>>       <stable_url_ref>. That tree is not included here because it is too
>>
>>       long (Section 3.4 of [RFCXXXX]). Instead, subtrees are provided
>>
>>       for the reader's convenience.
>>
>>
>>
>>    These guidelines take precedence over the generic guidance in
>>
>>    Section 3 of [RFC8340].
>>
>> ==
>>
>>
>>
>> My 2 cents
>>
>>
>>
>> Italo
>>
>>
>>
>> *From:* Qin Wu <bill.wu@huawei.com>
>> *Sent:* giovedì 29 febbraio 2024 02:51
>> *To:* Mahesh Jethanandani <mjethanandani@gmail.com>;
>> mohamed.boucadair@orange.com
>> *Cc:* netmod@ietf.org
>> *Subject:* Re: [netmod] Long trees RE: Next steps for
>> draft-ietf-netmod-rfc8407bis
>>
>>
>>
>> +1,  a few thoughts to share.
>>
>>
>>
>> I know this is tricky question related to tooling or artifact generation
>> and representation.
>>
>> I am wondering whether we can make YANG tree diagram in a "collapsed"
>> state where all the Leaf nodes and only leaf nodes are hidden from view
>> until its parent node is expanded, which can improve readability of the
>> tree diagram,
>>
>> In many cases can greatly reduce the size of YANG tree diagram, make it
>> fit into one page.
>>
>>
>>
>> Moving compete tree diagram or artifacts is another option we can pursue.
>> Also generating YANG tree along with YANG file in
>> https://github.com/YangModels/yang/tree/main/standard/ietf
>>
>> Is another option we can take a look at.
>>
>>
>>
>> -Qin
>>
>> *发件人**:* netmod [mailto:netmod-bounces@ietf.org <netmod-bounces@ietf.org>
>> ] *代表 *Mahesh Jethanandani
>> *发送时间:* 2024年2月29日 7:02
>> *收件人:* mohamed.boucadair@orange.com
>> *抄送:* netmod@ietf.org
>> *主题:* Re: [netmod] Long trees RE: Next steps for
>> draft-ietf-netmod-rfc8407bis
>>
>>
>>
>> I would agree with Andy that it is not clear how long is “too long”.
>>
>>
>>
>> BGP YANG model, which is perhaps one of the biggest models at 150 pages
>> long, has multiple tree diagrams none of which are more than one page long.
>>
>>
>>
>> If the complete tree diagram is too long, could it moved to the Appendix,
>> instead of banishing it from the document completely? Sorry Jan, but I hope
>> no one is cutting down trees to read the entire tree diagram. Sometimes,
>> albeit rarely, it is helpful to have the complete tree diagram handy to
>> reference where a particular node is in the tree.
>>
>>
>>
>> Cheers.
>>
>>
>>
>> On Feb 28, 2024, at 8:29 AM, mohamed.boucadair@orange.com wrote:
>>
>>
>>
>> Hi Jan,
>>
>>
>>
>> Thanks for the comments.
>>
>>
>>
>> Here is a first attempt to address the long trees point while taking into
>> account expanded/unexpanded uses:
>>
>>
>>
>> NEW:
>>
>>    YANG tree diagrams provide a concise representation of a YANG module
>>
>>    and SHOULD be included to help readers understand YANG module
>>
>>    structure.  If the complete tree diagram for a module becomes too
>>
>>    long, the diagram SHOULD be split into several smaller diagrams.  If
>>
>>    the complete tree diagram is too long even with groupings unexpanded
>>
>>    (Section 2.2 of [RFC8340]), authors SHOULD NOT include it in the
>>
>>    document.
>>
>>
>>
>>    These guidelines take precedence over the generic guidance in
>>
>>    Section 3 of [RFC8340].
>>
>>
>>
>> For convenience a diff for the proposed change can be seen
>> https://author-tools.ietf.org/api/iddiff?url_1=https://boucadair.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://boucadair.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt
>>
>>
>>
>> Cheers,
>>
>> Med
>>
>>
>>
>> *De :* Jan Lindblad <janl@tail-f.com>
>> *Envoyé :* mercredi 28 février 2024 15:21
>> *À :* BOUCADAIR Mohamed INNOV/NET <mohamed.boucadair@orange.com>
>> *Cc :* netmod@ietf.org
>> *Objet :* Re: [netmod] Next steps for draft-ietf-netmod-rfc8407bis
>>
>>
>>
>> Med, author team,
>>
>>
>>
>> Thank you for taking the time to get this work done, and well done! This
>> is one of those fundamental bricks that saves time and improves quality for
>> the entire YANG community.
>>
>>
>>
>> I read the -09 version and like what I see. I have a couple of minor
>> suggestions you might consider.
>>
>>
>>
>> + In section 3.4 about tree diagrams, the section text is already
>> advocating intermixing smaller tree snippets with explanations (which is
>> great), but I wish we could say that
>>
>> tree diagrams of entire modules SHOULD NOT be included. Just a waste of
>> forest and attention span, imho.
>>
>>
>>
>> + In section 4.2 about choice of prefixes, it is said that "Prefix values
>> SHOULD be short but are also likely to be unique." I used to say the same
>> thing. In recent years, however, I have started to stress the importance of
>> uniqueness much more. I'd say something like "Prefix values SHOULD be
>> selected carefully to be unique, and ideally not too long." The reason for
>> my change is I have met several engineers who have been deeply confused (to
>> the point of costing real money) when the same prefix has shown up in
>> multiple places. It's just an unnecessary part of the learning curve
>> associated with YANG.
>>
>>
>>
>> In fact, I have started to recommend people to set the prefix to equal
>> the module name. This also solves another problem, which is that the
>> "prefixes" you see in RESTCONF are module names, and the confusion of what
>> to use where is sometimes suffocating. I understand if many think I'm going
>> overboard here, but when we pretend that modules don't have prefixes, only
>> module names, there is a lot less friction in learning the ropes.
>>
>>
>>
>> + In section 4.6.2 regarding useless (in YANG Context) functions in the
>> XPath function library, it is said that the "YANG compiler" should return
>> false, etc. Better wording might be that the XPath execution environment
>> (or something) should return false, etc. The YANG compiler is not even
>> running when the calls to those functions are happening.
>>
>>
>>
>> + In section 4.11.5 regarding booleans, it is said that booleans can take
>> values true and false. This is true in mathematics :-) but in YANG a
>> boolean leaf can additionally take the "value" of "not set". Actually, "not
>> set" is a possibility for leafs in general, unless it is declared mandatory
>> true, or has a default. In my experience, one of the most common YANG
>> modeling issues is when people model a leaf foo, which isn't mandatory, has
>> no default and the description statement does not say what happens if the
>> leaf is not set. In many cases, there is a sort of natural meaning, but
>> with booleans leafs in particular, the absence of the leaf is typically
>> highly ambiguous. I think this hole merits a recommendation clause in the
>> I-D.
>>
>>
>>
>> Best Regards,
>>
>> /jan
>>
>>
>>
>>
>>
>>
>>
>> On 28 Feb 2024, at 10:51, mohamed.boucadair@orange.com wrote:
>>
>>
>>
>> Hi all,
>>
>> I think that this version is ready for the WGLC.
>>
>> The document fully covers the items promised when requesting adoption
>> [1]. As listed in the ACK section, we also solicited and integrated
>> feedback from many yangdoctors, solicited SAAG WG to review the security
>> text, etc. Refer to 1.1 for a comprehensive list of the changes.
>>
>> Cheers,
>> Med
>>
>> [1] Slide#7 of
>> https://datatracker.ietf.org/meeting/117/materials/slides-117-netmod-7-guidelines-for-authors-and-reviewers-of-documents-containing-yang-data-models-00
>>
>>
>>
>> -----Message d'origine-----
>> De : I-D-Announce <i-d-announce-bounces@ietf.org> De la part de
>> internet-drafts@ietf.org
>> Envoyé : mercredi 28 février 2024 10:01
>> À : i-d-announce@ietf.org
>> Cc : netmod@ietf.org
>> Objet : I-D Action: draft-ietf-netmod-rfc8407bis-09.txt
>>
>> Internet-Draft draft-ietf-netmod-rfc8407bis-09.txt is now available.
>> It is a work item of the Network Modeling (NETMOD) WG of the IETF.
>>
>>   Title:   Guidelines for Authors and Reviewers of Documents
>> Containing YANG Data Models
>>   Authors: Andy Bierman
>>            Mohamed Boucadair
>>            Qin Wu
>>   Name:    draft-ietf-netmod-rfc8407bis-09.txt
>>   Pages:   84
>>   Dates:   2024-02-28
>>
>> Abstract:
>>
>>   This memo provides guidelines for authors and reviewers of
>>   specifications containing YANG modules, including IANA-maintained
>>   modules.  Recommendations and procedures are defined, which are
>>   intended to increase interoperability and usability of Network
>>   Configuration Protocol (NETCONF) and RESTCONF protocol
>>   implementations that utilize YANG modules.  This document obsoletes
>>   RFC 8407.
>>
>>   Also, this document updates RFC 8126 by providing additional
>>   guidelines for writing the IANA considerations for RFCs that
>> specify
>>   IANA-maintained modules.
>>
>> The IETF datatracker status page for this Internet-Draft is:
>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdata
>> <https://data/>
>> tracker.ietf.org%2Fdoc%2Fdraft-ietf-netmod-
>> rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C51672231
>> 30c943a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C
>> 638447076716455966%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjo
>> iV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=s5VX9Hb%2Fl
>> P9v5QurysF69syyEyba9yYss7xd7K5E2FE%3D&reserved=0
>>
>> There is also an HTML version available at:
>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
>> <https://www/>.
>> ietf.org%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis-
>> 09.html&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943
>> a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638447
>> 076716464395%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
>> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=%2Br3nHahSq8OV24f
>> hFxBkJaqY43Q0GUxcbPZSFhji4uk%3D&reserved=0
>>
>> A diff from the previous version is available at:
>> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fauth
>> <https://auth/>
>> or-tools.ietf.org%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis-
>> 09&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943a5a4c
>> 608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63844707671
>> 6470644%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC
>> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=zo%2FrtFJrYJkJXOceIpzR
>> mlGAQF2c8m9Z%2F0vShl5o8gQ%3D&reserved=0
>>
>> Internet-Drafts are also available by rsync at:
>> rsync.ietf.org::internet-drafts
>>
>>
>>
>>
>> ____________________________________________________________________________________________________________
>> Ce message et ses pieces jointes peuvent contenir des informations
>> confidentielles ou privilegiees et ne doivent donc
>> pas etre diffuses, exploites ou copies sans autorisation. Si vous avez
>> recu ce message par erreur, veuillez le signaler
>> a l'expediteur et le detruire ainsi que les pieces jointes. Les messages
>> electroniques etant susceptibles d'alteration,
>> Orange decline toute responsabilite si ce message a ete altere, deforme
>> ou falsifie. Merci.
>>
>> This message and its attachments may contain confidential or privileged
>> information that may be protected by law;
>> they should not be distributed, used or copied without authorisation.
>> If you have received this email in error, please notify the sender and
>> delete this message and its attachments.
>> As emails may be altered, Orange is not liable for messages that have
>> been modified, changed or falsified.
>> Thank you.
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>>
>>
>>
>> ____________________________________________________________________________________________________________
>>
>> Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
>>
>> pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
>>
>> a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
>>
>> Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.
>>
>>
>>
>> This message and its attachments may contain confidential or privileged information that may be protected by law;
>>
>> they should not be distributed, used or copied without authorisation.
>>
>> If you have received this email in error, please notify the sender and delete this message and its attachments.
>>
>> As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
>>
>> Thank you.
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>>
>>
>>
>>
>> Mahesh Jethanandani
>>
>> mjethanandani@gmail.com
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> ____________________________________________________________________________________________________________
>>
>> Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
>>
>> pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
>>
>> a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
>>
>> Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.
>>
>>
>>
>> This message and its attachments may contain confidential or privileged information that may be protected by law;
>>
>> they should not be distributed, used or copied without authorisation.
>>
>> If you have received this email in error, please notify the sender and delete this message and its attachments.
>>
>> As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
>>
>> Thank you.
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>>
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>>
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>>
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>