Re: [netmod] tree diagram guidelines

Andy Bierman <andy@yumaworks.com> Fri, 08 December 2017 22:21 UTC

Return-Path: <andy@yumaworks.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 C2F011270AE for <netmod@ietfa.amsl.com>; Fri, 8 Dec 2017 14:21:03 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.6
X-Spam-Level:
X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=yumaworks-com.20150623.gappssmtp.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 5H4Q4VJqRM-T for <netmod@ietfa.amsl.com>; Fri, 8 Dec 2017 14:21:00 -0800 (PST)
Received: from mail-lf0-x22e.google.com (mail-lf0-x22e.google.com [IPv6:2a00:1450:4010:c07::22e]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 4998312426E for <netmod@ietf.org>; Fri, 8 Dec 2017 14:21:00 -0800 (PST)
Received: by mail-lf0-x22e.google.com with SMTP id x204so13297032lfa.11 for <netmod@ietf.org>; Fri, 08 Dec 2017 14:21:00 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yumaworks-com.20150623.gappssmtp.com; s=20150623; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc; bh=Sfgp9WbO42Dd+nX2JnE5+DYFWMqfg/tFbmPz8iu0PQo=; b=cvJ3Ze8g9eU3C3MNjIC1b9vdMg115etPf3Dbf2zzfGLnkiAzLPDCv5tw9xTDdcCO1x moViGQ4/bBhm3mTeDddVtAiv5mog9eQnsH0vkafnSAm+dGhTUiwVCVK+asT9hsInHrTI IQUvTzgOMnzWJIxfpwX9RVxdx4fFljYp0nBWEWmoaI0jfZG4M/kP3p7G2q9DhIBtGBuB 4Nv1lf1V4V7fPs4wD11hLEuw5R8k+TppLSpC3pmZkCUDffgfYj2Z+CfxOlHuhaC+37f6 bG7lSuzaO62xND99VqIIIqgPZuQv4mCHqpUVsWj5Yj9wuRPA3MLwMC2z39gXR+eO3wpo ZY+g==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:in-reply-to:references:from:date :message-id:subject:to:cc; bh=Sfgp9WbO42Dd+nX2JnE5+DYFWMqfg/tFbmPz8iu0PQo=; b=gby6LAVtnEpJgMBrZwbPJZRX/rcnRg18is5BBjn2R480J6W7pVzwYIJqkAgnPA+574 xsDwSlxCDWl/bTA66LmGU1i5NcLJRlxPLGi5N1UltUziwthgofPOzIjrnLka5nW8mPoi LQyYoa56AHqCd8ZxFYSe+tlgNLTl9/n2XkcNpUfHIJlaJIT2unjYbsCNrXBU0qc7fH6r 803rZJgpk+MKjyPkPcP6ite5ar7l5UdRRVk6zWfbNYypU3O4Phshh1CXGbamHiVKZWoH PtB9Fg4gNQ3m7dUYGtHaFWEN7dS6jiE+aYsMH/lClH+eXpiIX35gcbt65VdaVLaFKzqs TXxA==
X-Gm-Message-State: AKGB3mKy7AQ8EUTlO1Nkngv+mUQoVJKHJ4NRYe+jnT94Sj4nmeBvEHr+ 1q80PPIW3wLdRMB7dnYbB+Ir/7GCT3TSeVFJz4INDw==
X-Google-Smtp-Source: AGs4zMbSZ7w9NIEkzWDOG38WjxnpE80e/K8kCVlThdRL/5r40JoxCcLeBFQbTdLJJ+0jwE7lTPOr8k8YP+jN/td8vMs=
X-Received: by 10.46.57.10 with SMTP id g10mr7463130lja.77.1512771658502; Fri, 08 Dec 2017 14:20:58 -0800 (PST)
MIME-Version: 1.0
Received: by 10.25.33.81 with HTTP; Fri, 8 Dec 2017 14:20:57 -0800 (PST)
In-Reply-To: <4df13805-f4c8-89da-f986-64da816bea0b@labn.net>
References: <20171115.101454.1576716701146734257.mbj@tail-f.com> <bb0f2cf8-ca46-21af-02cd-79970a08db7e@cisco.com> <0696749C-0E80-40CC-9905-BD8187CB6D78@gmail.com> <014a01d35e87$98797950$c96c6bf0$@gmail.com> <00143927-dc4d-5db8-e3ce-dbd56366a06c@labn.net> <20171117070043.pm7rn25yj3hxum3q@elstar.local> <4df13805-f4c8-89da-f986-64da816bea0b@labn.net>
From: Andy Bierman <andy@yumaworks.com>
Date: Fri, 8 Dec 2017 14:20:57 -0800
Message-ID: <CABCOCHTS55b_b0X+WcQvMgtSg5GC-HzkTCMx5FN74jy+YwKFaw@mail.gmail.com>
To: Lou Berger <lberger@labn.net>
Cc: Mehmet Ersue <mersue@gmail.com>, Mahesh Jethanandani <mjethanandani@gmail.com>, Robert Wilton <rwilton@cisco.com>, NetMod WG <netmod@ietf.org>
Content-Type: multipart/alternative; boundary="089e082f5ce454ef1f055fdb99d2"
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/VPB17QsMRWv9o_o1NU-0CwF1VzE>
Subject: Re: [netmod] tree diagram guidelines
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
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: Fri, 08 Dec 2017 22:21:04 -0000

Hi,

These changes are OK with me.



Andy


On Thu, Dec 7, 2017 at 3:38 PM, Lou Berger <lberger@labn.net> wrote:

> Hi,
>
> Following up on this discussion (and hoping to wrap it up):
>
> I have created two  wikis off of
> https://trac.ietf.org/trac/netmod/wiki/WikiStart, one for 6087bis
> content and the other for section 3 of tree diagrams.  I also propose
> the following changes to the tree-diagrams draft:
>
> To section 3 intro, add:
>     For the most current quidelines being developed, please see the IETF
> NetMod Working
>    Group Wiki, see:  https://trac.ietf.org/trac/netmod/wiki/WikiStart
>
> Add :
>   3.2.  Groupings
>
>    If the YANG module is comprised of groupings only, then the tree
>    diagram should contain the groupings.  The 'pyang' compiler can be
>    used to produce a tree diagram with groupings using the "-f tree --
>    tree-print-groupings" command line parameters.
>
> And to section 3.3, start with:
>
>    Tree diagrams can be split into sections to correspond to document
>    structure.
>
> For 6087 bis, I think section 3.4 gets replaced with something like.
>
>     YANG tree diagrams provide a concise representation of a YANG module,
>    and SHOULD be included to help readers understand YANG module
>     structure.  Guidelines on tree diagrams can be found in Section 3 of
>     [I-D.ietf-netmod-yang-tree-diagrams].
>
> These changes can be found at:
> https://github.com/netmod-wg/yang-tree-diagrams/commit/
> 53919e0a4549c285758eb5aaaf02cf980269afff
>
> This leaves the intended status as the key open issue on the draft.
>
> Lou
>
>
> On 11/17/2017 2:00 AM, Juergen Schoenwaelder wrote:
> > I am confused. I think there was some consensus to
> >
> > - include all tree related guidelines in the tree document, remove all
> tree
> >   related guidelines from 6087bis and have 6087bis point to the tree
> document
> >   (which it already does)
> >
> > The rest is pointless since AFAIK there is no wiki guidelines pages to
> > point to and there is AFAIK nobody in place to actually maintain such
> > a wiki page. Perhaps a wiki is the future but until future has
> > arrived, we should not point to it.
> >
> > The other proposal I heard was to have a landing page that points to
> > the current guideline work which points to the relevant documents. A
> > wiki pointing to RFCs and ID, not RFC pointing to wikis. So this does not
> > affect the documents.
> >
> > /js
> >
> > PS: I am happy to add pointers to guidelines as a section to the
> >     wikipedia page.
> >
> > On Fri, Nov 17, 2017 at 07:42:33AM +0800, Lou Berger wrote:
> >> To circle back to this.  My sense of this discussion (as contributor) is
> >> (a) the tree diagrams draft should be updated to point to a "guidelines"
> >> wiki page for "the most current guidelines"
> >> (b) the tree diagrams draft should be updated to include a full set of
> the
> >> current tree related guidelines
> >> (c) 6087bis should be updated to point to a "guidelines" wiki page for
> "the
> >> most current guidelines"
> >> (d) 6087bis should have it's tree guidelines point to the tree diagrams
> >> document -- in addition to pointing to the wiki
> >>
> >> Does this sound right?
> >>
> >> Lou
> >> (as tree co-author)
> >>
> >> On 11/16/2017 11:04 AM, Mehmet Ersue wrote:
> >>> The Wiki is useful as a starting point providing a collection of
> pointers to guideline RFCs and the bis-revisions in development.
> >>>
> >>> Cheers,
> >>> Mehmet
> >>>
> >>>> -----Original Message-----
> >>>> From: netmod [mailto:netmod-bounces@ietf.org] On Behalf Of Mahesh
> >>>> Jethanandani
> >>>> Sent: Thursday, November 16, 2017 7:39 AM
> >>>> To: Robert Wilton <rwilton@cisco.com>
> >>>> Cc: netmod@ietf.org
> >>>> Subject: Re: [netmod] tree diagram guidelines
> >>>>
> >>>> Other SDOs can and follow the work in IETF through the RFCs we
> publish.
> >>>> They do not follow wiki’s, unless the document itself says, “here are
> the
> >>>> guidelines, but if you are looking for the latest, go to this wiki”.
> I therefore
> >>>> would support the proposal outlined below. It gives the SDO a stable
> point of
> >>>> reference with a document, which gets updated occasionally, but also
> allows
> >>>> them to peak at what is coming down the pipeline.
> >>>>
> >>>> Thanks.
> >>>>
> >>>>> On Nov 15, 2017, at 6:53 PM, Robert Wilton <rwilton@cisco.com>
> wrote:
> >>>>>
> >>>>> I liked the suggestion from Chris Hopps:
> >>>>>
> >>>>> I think that it was along the lines of ...
> >>>>>
> >>>>> The RFC contains a reference at the top that states that updates to
> the
> >>>> guidelines is available on a wiki at ....
> >>>>> Every few years the guidelines on the wiki can be folded into a
> latest
> >>>> version of the guidelines draft.
> >>>>> 6087bis looks to be 3.5 years old.  Should folks, e.g. at BBF,,
> IEEE, or MEF be
> >>>> using the latest draft guidelines, or should then use the published
> RFC until
> >>>> 6087bis is actually republshed?
> >>>>> Thanks,
> >>>>> Rob
> >>>>>
> >>>>>
> >>>>> On 15/11/2017 10:14, Martin Bjorklund wrote:
> >>>>>> Hi,
> >>>>>>
> >>>>>> There was a proposal in the meeting today to have the guidelines for
> >>>>>> tree diagrams in a wiki, instead of having them in 6087bis or in the
> >>>>>> tree diagram document.
> >>>>>>
> >>>>>> Was the proposal really to have a wiki for just the tree guidelines,
> >>>>>> or was the proposal to withdraw 6087bis from the process and instead
> >>>>>> publish all guidelines as a wiki?
> >>>>>>
> >>>>>> If it is the former, is it really worth it?
> >>>>>>
> >>>>>> Advantages with a wiki:
> >>>>>>
> >>>>>>    +  It can be updated more easily
> >>>>>>
> >>>>>> Some drawbacks:
> >>>>>>
> >>>>>>    -  It can be updated more easily
> >>>>>>       (meaning they are less stable)
> >>>>>>
> >>>>>>    -  Wikis tend to not be alive after some time, and are not that
> >>>>>>       easy to find.  Just try to find the various YANG-related wikis
> >>>>>>       we've tried to maintain over the years.
> >>>>>>
> >>>>>>    -  Links in RFCs also have problems.  Sites are re-orginized etc.
> >>>>>>       As an example, the link to the security guidelines template in
> >>>>>>       RFC 6087 doesn't work anymore.
> >>>>>>
> >>>>>>    -  People that are looking for a stable reference will have
> problems
> >>>>>>       (I think Rob mentioned that IEEE still refer to RFC 6087
> (which
> >>>>>>       is understandable; that's the published version).
> >>>>>>
> >>>>>>    -  Who maintains the Wiki, and what are the rules for updating
> it?
> >>>>>>
> >>>>>>
> >>>>>> I suggest we have the tree-related guidelines (actually just a few
> >>>>>> sentences) in the tree draft, and since 6087bis already refers to
> >>>>>> this document it is not a big problem that guidelines are spread out
> >>>>>> over several documents that are difficult to find.
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> /martin
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> 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
> >>>> Mahesh Jethanandani
> >>>> mjethanandani@gmail.com
> >>>>
> >>>> _______________________________________________
> >>>> 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
>
>