Changes between Version 26 and Version 27 of yang-doctors-review


Ignore:
Timestamp:
31/07/20 15:41:06 (14 months ago)
Author:
mersue@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • yang-doctors-review

    v26 v27  
    1111== Quick Links ==
    1212
    13 * [http://www.ietf.org/iesg/directorate/yang-doctors.html YANG Doctors home page]
    14 * [https://datatracker.ietf.org/group/yangdoctors/about/ YANG Doctors review tracking] [[br]]
     13* [https://datatracker.ietf.org/group/yangdoctors/about/ YANG Doctors home page]
     14* [https://datatracker.ietf.org/group/yangdoctors/reviews/ YANG Doctors review tracking] [[br]]
    1515
    1616== YANG Doctors Review Process ==
     
    1818=== Purpose ===
    1919
    20 The YANG doctors (reviewers) are supposed to help the OPS AD responsible for Network Management to review YANG documents that are destined to be on the IESG agenda.[[br]]
    21 The YANG doctors can also act as NETCONF/YANG advisors to WGs in any area of the IETF. Such is normally arranged between the WG chairs and the responsible ADs.
     20The YANG doctors (reviewers) are supposed to help the OPS AD responsible for Network Management to review documents containing a YANG module that are destined to be published.[[br]]
     21The YANG doctors can also act as NETCONF/YANG advisors to WGs in any area of the IETF. Such is normally arranged between the WG chairs and the responsible ADs. [[BR]]
    2222
    23 All YANG documents will be passed by a YANG doctor reviewer before they will be approved by the IESG. The YANG doctors review can be done during the development as an early review. The review must be done during or after the Working Group Last Call but at the latest before the IETF Last Call. If there was no review request, the review will be conducted during the IETF Last Call.
     23All documents with a YANG module will be passed by a YANG doctors review before they will be approved by the IESG.  [[br]]
     24A YANG Doctors review '''MUST''' be done before or during WG LC. The review '''MAY''' be repeated during the IETF LC with the same reviewer if WG chairs see it as helpful. Early reviews before WGLC '''MAY''' be done with a document assumed to be stable if the WG needs particular help and to catch up issues early especially regarding YANG module structure etc.[[BR]] [[br]]
     25As a general rule, reviews shall be done before or during the WGLC. A late review during IETF LC is the last resort and should be avoided.
    2426
     27=== Schedule and Deadlines ===
     28The YANG doctors are all volunteers so it may take some time. The review time for documents are proposed as below:
     29
     30   * WG document going to WGLC: The general practice is 2 weeks (can be extended up to 4 weeks).
     31   * WG document under development (Early Review): Usually 3 weeks (can be extended up to 8 weeks).
     32   * Stable non-WG document planned to publish: Initial deadline for 4 weeks, reviewed as best effort.
     33
     34The deadline can be extended if agreed by the involved parties.
    2535
    2636=== How to request YANG Doctors Review? ===
    2737
    28 ADs and WG chairs responsible for I-Ds with YANG modules should enter the review request directly via the datatracker draft page. [[br]]
    29 Non-WG documents can only be reviewed if the WG chair states that there is a plan for adoption and the YANG module is ready for review. [[br]]
     38ADs and WG chairs responsible for a document with YANG modules are in charge to enter the review request directly via the datatracker page of the draft. [[br]]
     39Non-WG documents can only be reviewed if the WG chair states that there is a plan for adoption and the YANG module is ready for review or an AD states that the draft is stable and it is going to be published as an AD sponsored RFC. [[br]]
     40
    3041To request a review please:
    3142   * Sign-in to the Datatracker and go to the draft page, e.g. https://datatracker.ietf.org/doc/draft-ietf-netconf-keystore/
    3243   * Click on the button "Request review",
    33    * Choose the type of review (Early, Last Call, Telechat) and set a deadline for 3-4 weeks,
     44   * Choose the type of review (Early, Last Call, Telechat) and set a deadline fitting the document type as explained above,
    3445   * If required a particular YANG doctor can be proposed as reviewer in the comments.
    35    * Please inform the OPS ADs and the YANG doctors secretary for the requested review.
    36 
    3746
    3847=== Assignment of YANG Doctors to reviews and Workload ===
    3948
    4049YANG Doctors secretary assigns open requests to reviewers using the review tracking tool on datatracker. The tool on datatracker proposes a reviewer based on the round robin approach. [[br]]
     50If the document was reviewed earlier the tool recommends the same reviewer again. [[br]]
     51
    4152Following the assignment of a reviewer to a YANG module the tool generates an email informing the reviewer by indicating the type of review (Early, LC or Telechat) and the review deadline.
    4253[[BR]] [[br]]
    43 YANG doctors can enter their unavailability into their datatracker account profile to avoid a wrong assignment during their absence.
    44 
    45 === Schedule and Deadlines ===
    46 The YANG doctors are all volunteers. The review time for documents under development (Early Review) is usually set to 3 weeks. Documents in WGLC or in IETF Last Call are reviewed with a 2 weeks deadline. The deadline can be extended if proposed by the requester and agreed by the involved parties. [[BR]]
    47 As a general rule, reviews after the telechat date are not useful, but check the [https://datatracker.ietf.org/idtracker/ draft tracker] to see if the document has been deferred.
     54YANG doctors can enter their unavailable times into their datatracker account profile to avoid an assignment during their absence.
    4855
    4956=== What to look for during a review ===
    5057The most important item is to give the AD a sense of how important it is that they pay attention to the document.
    5158[[BR]]
    52 For YANG reviews the YANG Doctors will apply the RFC6087bis document on the Guidelines for Authors and Reviewers of YANG Data Model Documents [https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc6087bis/]. The YANG language syntax and semantics should be analyzed. The compliance with [https://tools.ietf.org/html/draft-ietf-netmod-revised-datastores Network Management Datastore Architecture] should to be ensured (see also [https://tools.ietf.org/html/draft-dsdt-nmda-guidelines NMDA guidelines]).
    53 
    54 === Review Information ===
    55 Under some circumstances, the YANG doctors might discover open issues or provide feedback worth documenting for the larger community. While the NETMOD WG still work on RFC6087bis, updating this document is preferred. If the topic is not appropriate for the RFC6087bis or if RFC6087bis has already been published, then this must be documented on the YANG questions/answers WIKI [https://trac.ietf.org/trac/ops/wiki/YANGDoctorsFAQ].
     59For YANG reviews the YANG Doctors will apply the BCP 216 (RFC 8407) on the Guidelines for Authors and Reviewers of YANG Data Model Documents [https://datatracker.ietf.org/doc/rfc8407/]. The YANG language syntax and semantics should be analyzed. The compliance with [https://tools.ietf.org/html/rfc8342 Network Management Datastore Architecture] should to be ensured (see also [https://tools.ietf.org/html/draft-dsdt-nmda-guidelines-01 NMDA guidelines]).
    5660
    5761=== Where to enter the review result ===
    5862YANG Doctors enter the review result into the review tracking tool with following procedure:
    59    * The reviewer opens the corresponding draft review request page from the list at: https://datatracker.ietf.org/dir/yangdoctors/reviews/
     63   * The reviewer opens the corresponding draft review request page from the list at: [https://datatracker.ietf.org/group/yangdoctors/reviews/]
    6064   * Clicks on the "Complete review" button
    6165   * Enters the review state, the number of the reviewed revision, and the review result.
    6266   * In case the reviewer enters the review result directly into the tool or uploads a text file, the tool generates an email to YANG Doctors maillist, draft authors and the related WG maillist.
    63    * PS: Please remove ietf@ietf.org from CC until the datatracker admin removes it from the default list. Do not remove any other parts.
    6467   * Please choose as review state any of '''Not ready''', '''On the Right Track''', '''Almost ready''', '''Ready with issues''', '''Ready with Nits''' and '''Ready'''. [[BR]]
    6568
    66 '''Ready''' means the reviewer does not have any real comments to the document. '''Ready with nits''' means there was something in the document which might require new revision, for example typo, or changing language more readable, but not something that really would require ADs to put discuss on the document. '''Ready with issues''' means there is something in the document that might require ADs to put discuss on the document, or which they need to check more carefully, i.e. some kind of security issue.
     69'''Ready''' means the document is in good shape and the reviewer does not have any real comments to the document.[[BR]]
     70'''Ready with nits''' means there was something in the document which might require new revision, for example typo, or changing language as more readable, but not something that really would require ADs to put discuss on the document. [[BR]]
     71'''Ready with issues''' means there is something in the document that might require ADs to put discuss on the document, or which they need to check more carefully, i.e. some kind of security issue.
    6772[[BR]][[br]]
    68 If the reviewer discovers an important issue that would require feedback from the entire IETF community, you may send to ietf@ietf.org instead of (or in addition to) the other mailing lists. If there's something the reviewer wants to share only with the ADs, a separate, ADDITIONAL, message will be sent, flagged as private, but also a note to the broader community, as above.
    69 [[BR]] [[br]]
    70 Please use the sample boilerplate below:
     73If the reviewer discovers an important issue that would require feedback from the entire IETF community, you may include ietf<at>ietf.org in addition to other mailing lists. If there's something the reviewer wants to share only with the ADs, an additional separate message can be sent to the AD, flagged as PRIVATE.
    7174[[BR]]
    72 {{{
    73 I have reviewed this document as part of the YANG doctors directorate's
    74 ongoing effort to review all IETF documents being processed by the IESG.  These
    75 comments were written with the intent of improving the operational aspects of the
    76 IETF drafts. Comments that are not addressed in last call may be included in AD reviews
    77 during the IESG review.  Document editors and WG chairs should treat these comments
    78 just like any other last call comments.
    79 }}}
    8075
    8176The assignment of reviews for YANG modules from external organizations will be listed on the YANG review history page at: https://trac.ietf.org/trac/ops/wiki/yang-doctors-review-history [[BR]]
    82 The review result will be sent as usual to YANG Doctors maillist, draft authors (<draft>.all@ietf.org) and the related WG maillist. Please provide review state and result as described above.
     77The review result will be sent as usual to YANG Doctors maillist, draft authors (<draft>.all<at>ietf.org) and the related WG maillist. Please provide review state and result as described above.
    8378
    8479=== Early Reviews ===
    8580Since YANG is a relatively new technology for some IETF working groups, proactive reviews from YANG doctors can be requested also in an early phase of the development (WG document under development). Our secretary assigns those documents when the responsible ADs or WG chairs signal some level of maturity.   
    86 Also, the WG chair can request an early review of the document he feels is almost ready, just to get early feedback on the document before the IETF LC. Early reviews are indicated in the assignment email generated by the datatracker, and they should be done within approx. two weeks to be useful for the WG. It’s expected that early reviews will imply multiple new draft versions. So the reviewer must be ready to follow this draft for some time.
    87 [[BR]] [[br]]
     81Also, the WG chair can request an early review of the document he feels is almost ready, just to get early feedback on the document before the IETF LC. Early reviews are indicated in the assignment email generated by the datatracker, and they should be done within approx. 3 weeks to be useful for the WG. It’s expected that early reviews will imply multiple new draft versions. So the reviewer must be ready to follow this draft for some time.
     82[[BR]]
    8883For some background information on early reviews, see EarlyReview.
    8984
     
    9388The reviewer should look whether the draft has changed since the last call review and briefly let the ADs know if any identified showstopper issues have been fixed or still remain (please CC YANG doctors secretaries as well, for tracking). Feel free to include your original review, just to provide a history. Particularly on these returning items, remember that the HTML-version of the draft (at https://tools.ietf.org/html/draft-ietf-xxx) provides precomputed diffs for WG docs.
    9489
     90=== Improvement of YANG language and usage guidelines ===
     91Under some circumstances, the YANG doctors might discover open issues in BCP 216 (RFC 8407) or provide feedback worth documenting for the larger community. This should be documented on the YANG questions/answers WIKI [https://trac.ietf.org/trac/ops/wiki/YANGDoctorsFAQ].
     92
    9593=== Useful email aliasses ===
    9694FYI, all existing aliases, along with its members, are documented at [http://tools.ietf.org/draft/aliases http://tools.ietf.org/draft/aliases].
    9795[[BR]] [[BR]]
    98 WG chairs may be reached at wgname-chairs@ietf.org.
     96WG chairs may be reached at wgname-chairs<at>ietf.org.
    9997[[BR]] [[br]]
    10098Replace draftname by draft-ietf-wg-topic (without -xx version):
    10199[[BR]]
    102 || draftname@ietf.org || Draft authors (for now, could change) ||
    103 || draftname.authors@ietf.org || Draft authors ||
    104 || draftname.chairs@ietf.org || WG Chairs (if the draft is a WG draft) ||
    105 || draftname.notify@ietf.org || The addresses entered into the tracker's email notification field for the draft ||
    106 || draftname.ad@ietf.org || The sponsoring AD, if the draft has gone to the IESG ||
    107 || draftname.all@ietf.org || All of the above, merged into one alias ||
     100|| draftname<at>ietf.org || Draft authors ||
     101|| draftname.authors<at>ietf.org || Draft authors ||
     102|| draftname.chairs<at>ietf.org || WG Chairs (if the draft is a WG draft) ||
     103|| draftname.notify<at>ietf.org || The addresses entered into the tracker's email notification field for the draft ||
     104|| draftname.ad<at>ietf.org || The sponsoring AD, if the draft has gone to the IESG ||
     105|| draftname.all<at>ietf.org || All of the above, merged into one alias ||
    108106