wiki:yang-doctors-review

YANG Doctor Detailed Review Procedure

Useful Contacts

Mailing list : yang-doctors<at>ietf.org

Shepherding Area Director :
Ignas Bagdonas ibagdona<at>gmail.com

Secretaries:
Mehmet Ersue mersue<at>gmail.com and Dan Romascanu dromasca<at>gmail.com

YANG Doctors Review Process

Purpose

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.
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.

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.

How to request YANG Doctors Review?

ADs and WG chairs responsible for I-Ds with YANG modules should enter the review request directly via the datatracker draft page.
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.
To request a review please:

  • Sign-in to the Datatracker and go to the draft page, e.g. https://datatracker.ietf.org/doc/draft-ietf-netconf-keystore/
  • Click on the button "Request review",
  • Choose the type of review (Early, Last Call, Telechat) and set a deadline for 3-4 weeks,
  • If required a particular YANG doctor can be proposed as reviewer in the comments.
  • Please inform the OPS ADs and the YANG doctors secretary for the requested review.

Assignment of YANG Doctors to reviews and Workload

YANG 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.
Following 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.

YANG doctors can enter their unavailability into their datatracker account profile to avoid a wrong assignment during their absence.

Schedule and Deadlines

The YANG doctors are all volunteers. The review time for documents in WGLC is usually 2 weeks. The deadline can be extended up to 4 weeks. For documents under development the general practice is to set a deadline for 3 weeks. The deadline for such documents can be extended upto 8 weeks. Non-WG documents get an initial deadline for 4 weeks but are reviewed as best effort.
As a general rule, reviews after the telechat date are not useful, but check the draft tracker to see if the document has been deferred.

What to look for during a review

The most important item is to give the AD a sense of how important it is that they pay attention to the document.
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 Network Management Datastore Architecture should to be ensured (see also NMDA guidelines).

Review Information

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.

Where to enter the review result

YANG Doctors enter the review result into the review tracking tool with following procedure:

  • The reviewer opens the corresponding draft review request page from the list at: https://datatracker.ietf.org/dir/yangdoctors/reviews/
  • Clicks on the "Complete review" button
  • Enters the review state, the number of the reviewed revision, and the review result.
  • 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.
  • PS: Please remove ietf@… from CC until the datatracker admin removes it from the default list. Do not remove any other parts.
  • Please choose as review state any of Not ready, On the Right Track, Almost ready, Ready with issues, Ready with Nits and Ready.

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.

If the reviewer discovers an important issue that would require feedback from the entire IETF community, you may send to ietf@… 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.

Please use the sample boilerplate below:

I have reviewed this document as part of the YANG doctors directorate's 
ongoing effort to review all IETF documents being processed by the IESG.  These 
comments were written with the intent of improving the operational aspects of the 
IETF drafts. Comments that are not addressed in last call may be included in AD reviews 
during the IESG review.  Document editors and WG chairs should treat these comments 
just like any other last call comments. 

The 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
The review result will be sent as usual to YANG Doctors maillist, draft authors (<draft>.all@…) and the related WG maillist. Please provide review state and result as described above.

Early Reviews

Since 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. 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.

For some background information on early reviews, see EarlyReview.

Re-Reviews

Once a reviewer has been assigned to a document, the reviewer is generally expected to stay with that document through its completion, even if additional reviewers are assigned. Accordingly, when a document was reviewed already by a particular reviewer and is then revised or scheduled for the IESG telechat, YANG Doctors secretary may reassign it to the same reviewer for a recheck.

The 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.

Useful email aliasses

FYI, all existing aliases, along with its members, are documented at http://tools.ietf.org/draft/aliases.

WG chairs may be reached at wgname-chairs@….

Replace draftname by draft-ietf-wg-topic (without -xx version):

draftname@… Draft authors (for now, could change)
draftname.authors@… Draft authors
draftname.chairs@… WG Chairs (if the draft is a WG draft)
draftname.notify@… The addresses entered into the tracker's email notification field for the draft
draftname.ad@… The sponsoring AD, if the draft has gone to the IESG
draftname.all@… All of the above, merged into one alias
Last modified 7 months ago Last modified on Sep 27, 2018, 4:14:42 AM