[yang-doctors] YANG FAQ Page - Assignments of Questions to answer WAS:FW: YANG FAQ page and Developing of the Answers

["Ersue, Mehmet (Nokia - DE/Munich)" <[e-mail]>]

Hi All,

This is the very first round of assignments for the YANG FAQ page clarifications and the drafting of answers.
So please bear with us and suggest what you would like to improve.
See the mail below for some details on the handling.

If for any reason you cannot provide a draft answer please let me know as soon as possible.
For some of the questions below there is an incomplete answer on the wiki page below:
https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors

1. Deviations versus if-feature? - Martin Björklund

2. Should NETCONF server export common YANG models? - Andy Bierman

3. Should Config, State, RPC, Notifications, etc. for a given protocol be all in one module, or different ones? (added by Rajiv Asati) - Lada Lhotka

4. Intended, Applied and Derived States? (added by Rajiv Asati) - Kent Watsen

5. Module Organization Illustration? (added by Rajiv Asati, answered by ...) - Balazs Lengyel

6. Can a leaf exist inside a module by itself (without a container)? - Carl Moberg

Thank you for your efforts in advance.

Mehmet

_____________________________________________
From: Ersue, Mehmet (Nokia - DE/Munich)
Sent: Sunday, June 05, 2016 8:05 PM
To: '[e-mail]' <[e-mail]>
Subject: YANG FAQ page and Developing of the Answers


Hi All,

Benoit proposed to update/maintain the YANG Wiki FAQ page. This is basically to do by
assigning questions to people and validating the drafted answer text on YANG doctor's list
(see attached mail).

As a result the Q/A page at https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors
will be updated with the validated answers.

As a starter I will assign the 6 questions currently on the FAQ page to people I assume can answer it appropriately.
We need to check whether the current answer on this page is sufficient and improve as necessary.
If you don't like the question formulation you can provide a better one in your draft.

Please send your proposed draft answer to [e-mail]<mailto:[e-mail]> for validation and use the answered question in the subject (at least partly if it is long).
PLMK with a short note if you feel uncomfortable with the assigned question.

I propose to note the assignments on the page below as a new category: YANG Questions and Answers
https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors-review-history

Please let us know the questions you think should be addressed on the FAQ page.
As a reminder the minutes of YANG editing and advice sessions are attached.

Any other suggestions are welcome.

Many Thanks.

Cheers,
Mehmet

--- Begin Message ---

-------- Forwarded Message --------
Subject:        IETF 93: YANG editing and advice session
Date:   Sun, 19 Jul 2015 17:26:24 +0200
From:   Benoit Claise <[e-mail]><mailto:[e-mail]>
To:     Benoit Claise <[e-mail]><mailto:[e-mail]>


1. prefix name advice
2. tunnel:
    no unified idea of the tunnel
    typdef for end points, for encaps
    where do we put the encap?
    ZITAO WANG: Huawei (for China Telecom)
    Andy: one place for common typedefs
    L3VPN, GRE, VLAN: different tunnel types
    Benoit: 5 or 6 tunnel
3. typedef for end points
    generic: could be done, but discussed happened and conclusion ->
not worth it
    Andy: like interface identityref
4. Andy: Grouping versus augment

5. maintainable over time
    like openconfig
6 augmentation and uses





.

--- End Message ---

--- Begin Message ---

-------- Forwarded Message --------
Subject:        Meeting minutes: IEFF 92 YANG editing and advice session, RFC 6087bis
Date:   Sun, 22 Mar 2015 20:07:23 -0500
From:   Benoit Claise <[e-mail]><mailto:[e-mail]>
To:     me <[e-mail]><mailto:[e-mail]>


Lada:
- lead address should be extending
- container that can be enabled/disabled
    canonical approach: with present, with leaf with default = true
    individual draft by Juergen (expire) or WIKI
- how to delete stuff from a grouping
    no possible
    advice: plan in advance, so that we have the common part in the grouping, then use extend the grouping
- granularity of module:
    small or big set of functions: it depends
- naming convention
    globalIpPool: ugly
    convention: global-ip-local

Martin:
- diffserv:
    different vendors have different structure?
    common model or multiple model?
- grouping and granularity

Andy:
- reusing data types:
    grouping/typdef
    RFC 6991

AI: single place with all YANG models,
        published ones
        WG ones
- attributes
    don't want to have them change on the fly
    current YANG: any single leaf can change 10000/s
    "only set when created"
    Dean: should it be in the description?

Tom:
- creating new type that can reused
- the tree ouput inb

--- End Message ---

--- Begin Message ---

Dear all,

Second topic now: The FAQ.

In my email below, I mentioned this point:


   4. YANG FAQ.
   At this point in time, I believe that the WIKI is the right way to go. We can see later how the content evolves. The first step is to update https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors with the typical questions received by YANG doctors, and maybe with content from Juergen's draft.

   We have a couple of questions already at https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors
   Btw, not too sure who answered the first two. This might be worth tracking.

   The types of questions we want to answer on that WIKI are:
       - stemming from previous YANG editing sessions, document reviews, or direct feedback from YANG modelers
         For example, Rajiv Asati added questions 3, 4, and 5
       - not addressed by RFC 6087bis (but which could belong there, to be decided)

   We might consider adding the content from https://tools.ietf.org/html/draft-schoenw-netmod-yang-pattern-00

   Exactly like for the document reviews, Dan will be assigning those questions to YANG doctors, who would be in charge of drafting an answer (before or after discussion on this list).

   The end goal is to provider YANG modelers/reviewers with two pointers
       RFC6087bis
       These FAQs
   If the answer is not in here (or RFC6020bis or RFC6244 or another RFC or ...), then we know we're missing something.

   I hope it makes sense. Let me know.

   Regards, Benoit

   =========================================


   Primary YANG doctor page to bookmark: http://www.ietf.org/iesg/directorate/yang-doctors.html
   From there, you can find the important links, including the review assignments:


*       YANG module security guidelines<http://trac.tools.ietf.org/area/ops/trac/wiki/yang-security-guidelines>
*       NETMOD WIKI<http://trac.tools.ietf.org/wg/netmod/trac/wiki>
*       NETCONF WIKI (tools, paper, presentations, tutorial)<http://trac.tools.ietf.org/wg/netconf/trac/wiki>
*       YANG review assignments<http://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors-review-history>
*       YANG review tools<http://trac.tools.ietf.org/area/ops/trac/wiki/yang-review-tools>
*       Historical page <http://trac.tools.ietf.org/area/ops/trac/wiki/yang-historical-data>
*       YANG Questions/Answers<https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors>



   Dear all,

   I've been waiting for a couple of days before answering, to allow for more YANG doctors feedback.

   First of, I believe that this priority list is right:


      The YANG doctors are all volunteers. Below are guidelines for response time
      1) WG document in WGLC: 2 - 4 weeks
      2) WG document under development: 2 - 8 weeks
      3) non-WG document: best effort (really)


   It's correct that we mainly/only receive requests from category 3 at this point, and I will be pushing back on those.

   2. Let's look at the stats for category 2 (no category 1 for now)
   One third of drafts containing YANG data models (only the ones that extract without problems) are WG documents.


      bclaise@bclaise-VirtualBox:~/ietf/draft-with-YANG-strict$ ls -l | wc -l
      119
      bclaise@bclaise-VirtualBox:~/ietf/draft-with-YANG-strict$ ls -l draft-ietf-* | wc -l
      39
      bclaise@bclaise-VirtualBox:~/ietf/draft-with-YANG-strict$



      bclaise@bclaise-VirtualBox:~/ietf/draft-with-YANG-strict$ ls  draft-ietf-*
      draft-ietf-bfd-yang-01.txt
      draft-ietf-ccamp-wson-yang-01.txt
      draft-ietf-dhc-dhcpv6-yang-01.txt
      draft-ietf-i2rs-rib-data-model-05.txt
      draft-ietf-i2rs-yang-l2-network-topology-02.txt
      draft-ietf-i2rs-yang-l3-topology-01.txt
      draft-ietf-i2rs-yang-network-topo-02.txt
      draft-ietf-idr-bgp-model-01.txt
      draft-ietf-ippm-twamp-yang-00.txt
      draft-ietf-isis-yang-isis-cfg-08.txt
      draft-ietf-l2tpext-keyed-v6-tunnel-yang-01.txt
      draft-ietf-l3sm-l3vpn-service-model-05.txt
      draft-ietf-lime-yang-oam-model-03.txt
      draft-ietf-lisp-yang-01.txt
      draft-ietf-lmap-yang-04.txt
      draft-ietf-netconf-restconf-12.txt
      draft-ietf-netconf-server-model-09.txt
      draft-ietf-netconf-yang-library-05.txt
      draft-ietf-netconf-yang-patch-08.txt
      draft-ietf-netconf-yang-push-02.txt
      draft-ietf-netconf-zerotouch-08.txt
      draft-ietf-netmod-acl-model-07.txt
      draft-ietf-netmod-rfc6087bis-06.txt
      draft-ietf-netmod-routing-cfg-21.txt
      draft-ietf-netmod-schema-mount-01.txt
      draft-ietf-netmod-syslog-model-07.txt
      draft-ietf-netmod-yang-metadata-07.txt
      draft-ietf-ospf-yang-04.txt
      draft-ietf-pim-yang-00.txt
      draft-ietf-rtgwg-policy-model-01.txt
      draft-ietf-rtgwg-yang-key-chain-02.txt
      draft-ietf-rtgwg-yang-rip-01.txt
      draft-ietf-spring-sr-yang-02.txt
      draft-ietf-teas-yang-rsvp-03.txt
      draft-ietf-teas-yang-te-03.txt
      draft-ietf-teas-yang-te-topo-04.txt
      draft-ietf-trill-yang-04.txt
      draft-ietf-trill-yang-oam-03.txt
      draft-ietf-trill-yang-pm-02.txt



   I expect that most NETCONF and NETMOD documents are fine from a YANG point of view.
   I also believe that some routing ones are lead by YANG experts, so we should be good.
   This still leaves us with some proactive work to do.

   3.
   As spotted by Dan, <http://www.ietf.org/iesg/directorate/yang-doctors.html> http://www.ietf.org/iesg/directorate/yang-doctors.html calls for reviews at WGLC, which is different from MIB documents reviews.

   I asked the Secretariat to include this update.
   OLD:
   All YANG documents will be passed by a YANG doctor reviewer before they will be approved by the IESG. The YANG doctor review must be done after the Working Group Last Call and before the IETF Last Call. ADs and WG chairs responsible on I-Ds that include YANG documents should ask the OPS ADs for a review as soon as the document completed WGLC.

   NEW:
   All YANG documents will be passed by a YANG doctor reviewer before they will be approved by the IESG. The YANG doctor review must be done after the Working Group Last Call and before the IETF Last Call. ADs and WG chairs responsible on I-Ds that include YANG documents should ask the OPS ADs for a review as soon as the document completed WGLC. Failing that request, the review will be conducted during the IETF Last Call.

   4. YANG FAQ.
   At this point in time, I believe that the WIKI is the right way to go. We can see later how the content evolves. The first step is to update https://trac.tools.ietf.org/area/ops/trac/wiki/yang-doctors with the typical questions received by YANG doctors, and maybe with content from Juergen's draft.

   5. Dan Romascanu proposes himself as YANG doctors secretary. Thanks for volunteering Dan.
   I have some visibility on the maturity of the YANG data models, so Dan and I could help with the early assignments. Note: Dan is on vacation till May 1st. If some YANG doctors don't want to be assigned YANG models for review, it's about time to tell us.

   Regards, Benoit




      On Fri, Apr 15, 2016 at 12:34 AM, Martin Bjorklund <<mailto:[e-mail]>[e-mail]<mailto:[e-mail]>> wrote:


         Juergen Schoenwaelder <[e-mail]<mailto:[e-mail]>> wrote:
         > The question is whether we want some sort of change control. For the
         > pattern, I tend to think having change control is a good thing since
         > the pattern should ideally after some discussion be stable and longer
         > time valid.
         >
         > If you have pattern, then write them down and send them here or to
         > NETMOD. Yeah, I know, this is old style...

         But we also would like to collect the patterns.


         Let's list some options:

         1) collect everything in one I-D, keep updating it, never publish as
            RFC.





      How would we tell the difference from a real I-D   ;-)




         2) collect everything in one I-D, keep updating it, publish "often" as
            an Informationl RFC

         3) gitbook (https://github.com/GitbookIO/gitbook)
            create a yang-doctors repo at github, publish often/automatically,
            either through gitbook.com<http://gitbook.com> or yang-central.org<http://yang-central.org> or something else

            write in markdown/asciidoc + graphics, check in to github

         4) wiki
            ietf or github wiki






      I think an IETF maintained WEB page is best

      Let's use the wiki page Benoit mentioned.




         1) is current state of affair, except it isn't really updated (it is
         updated locally, but the draft is still -00)

         2) gives us strict "change control", everything is properly reviewed,
         and adding new patterns will be slow

         3) doesn't give us normal ietf review process, but we can define our
         own review process.  easy for others to collaborate.  nice result;
         online, pdf, epub...

         4) doesn't give us normal ietf review process.  not as easy for others
         to collaborate.





      The YANG Patterns draft did not really get any interest, even though
      it was good work.  Not the first time that has happened.
      Maybe re-marketed as the YANG FAQ it will do better.

      Each entry should be "How do I do this? , w/answer"


      How do I link my list to the interfaces list?
         - interface-ref typedef
         - direct leafref
         - match key-stmt
         - augment
         - augment-when

      Where should I put must-stmts?

      How do I know if I need a must-stmt or not?
      What are easier ways to accomplish the same constraint?

      When should I define a grouping instead of inline definitions?
      (We do not agree on this in YD)

      When should I use a YANG feature?

      When should I defined a new module instead of adding
      a YANG feature + objects to an existing module?

      We could probably come up with 100 Q&A if we tried.


      Andy





         I would like to try option 3.  I think options 1 and 2 are the wrong
         tool for the problem.  Wikis rarely work well over time.  I don't know
         if option 3 works better over time, but I think it would be
         interesting to try it out.



         /martin

         _______________________________________________
         yang-doctors mailing list
         [e-mail]<mailto:[e-mail]>
         https://www.ietf.org/mailman/listinfo/yang-doctors






      _______________________________________________
      yang-doctors mailing list
      [e-mail]<mailto:[e-mail]>
      https://www.ietf.org/mailman/listinfo/yang-doctors





   _______________________________________________
   yang-doctors mailing list
   [e-mail]<mailto:[e-mail]>
   https://www.ietf.org/mailman/listinfo/yang-doctors

--- End Message ---