A Practical Guide toPROTO Shepherding
WG Chairs Training Lunch
IETF68 Prague
Margaret Wasserman
margaret@thingmagic.com
PROTO Goals
•Improve efficiency and transparency ofthe final stages of the IETF process
–Offload work from the IESG
–Maintain WG visibility and documentownership through RFC publication
PROTO History
•Started as an experiment about threeyears ago
•Now adopted IETF-wide in all areas
–Some WGs or documents may be handleddifferently at AD’s discretion
Definitive References
•Document Shepherding from WorkingGroup Last Call to Publication
–draft-ietf-proto-wgchair-doc-shepherding-09.txt
–Approved for publication as an Info RFC
•Requirements on I-D TrackerExtensions for Working Group Chairs
–draft-ietf-proto-wgchair-tracker-ext-03.txt
What is a PROTO Shepherd?
•The person responsible for shepherding anIETF document through the last stages of theIETF process
–From Publication Requested through RFCPublication
–Usually a WG Chair or Secretary
–Not the editor or author of the document
•Responsible for driving progress andmaintaining WG visibility and transparencyduring final phases
Choosing a Shepherd
•Usually a WG Chair or Secretary who is
–Not an author or editor of this document
–Not otherwise conflicted
•Shepherd may be chosen early for work splitbetween WG co-chairs
–Divide up documents when accepted as WG workitems
–Shepherd drives document from WG acceptancethrough RFC publication
Shepherding Tasks
•Provide the Document Shepherd Write-Up whenpublication is requested
•During AD Evaluation, manage discussion betweeneditors, working group, and the AD
•During an IETF Last Call, follow up on communityfeedback and review comments.
•During IESG evaluation, following up on all IESGfeedback
•Follow up on IANA and RFC Editor requests in thepost-approval stages
Document Shepherd Write-Up
•Answers questions (items 1.a to 1.j) to giveAD insight into the WG process
•Provides a Document Announcement Write-Up (item 1.k) that is included in the IESGballot and sent to the IETF when thedocument is approved for publication
•MUST be sent with publication request to theSecretariat (iesg-secretary@ietf.org) and theResponsible AD
Purpose of the Write-Up
•Encourages the Shepherd to takepersonal responsibility for determiningthat the proper WG process has beenfollowed
•Communicates history, issues andconcerns to the AD
Question 1.a
Who is the Document Shepherd for this document? Has theDocument Shepherd personally reviewed this version of thedocument and, in particular, does he or she believe this versionis ready for forwarding to the IESG for publication?
•Name one person (you) who will be shepherding thiswork.
•You MUST personally review this document
–ADs will bounce back documents if you answer “no”.
•You SHOULD be believe that this version is ready forpublication
–If not, you need to be very clear with your AD about why you aresubmitting it for publication over your own objections
Question 1.b
Has the document had adequate review both from key WGmembers and from key non-WG members? Does theDocument Shepherd have any concerns about the depth orbreadth of the reviews that have been performed?
•Again, you SHOULD answer yes to this question
–If the document has not been adequately reviewed, get itreviewed before submitting it for publication
–If you do have concerns, be clear about why you areforwarding it for publication, anyway
Question 1.c
Does the Document Shepherd have concerns that the documentneeds more review from a particular or broader perspective,e.g., security, operational complexity, someone familiar withAAA, internationalization or XML?
•This is your chance to ask the AD for help in gettingwider IETF review for your document
•If you include requests in this area and don’t see anyaction from the AD, follow up with the AD to getinformation about how to get this review
•It remains your responsibility to make sure that thedocument is adequately reviewed before publication
Question 1.d
Does the Document Shepherd have any specific concerns orissues with this document that the Responsible Area Directorand/or the IESG should be aware of? For example, perhaps heor she is uncomfortable with certain parts of the document, orhas concerns whether there really is a need for it. In any event,if the WG has discussed those issues and has indicated that itstill wishes to advance the document, detail those concernshere. Has an IPR disclosure related to this document beenfiled? If so, please include a reference to the disclosure andsummarize the WG discussion and conclusion on this issue.
•This is your opportunity to raise issues where youwould like the AD to check if the right decisions weremade. Also to alert the AD to issues that may beraised in IETF LC.
Question 1.e
How solid is the WG consensus behind this document? Does itrepresent the strong concurrence of a few individuals, withothers being silent, or does the WG as a whole understand andagree with it?
•Provide a frank summary of the WG consensusprocess
•If there is an issue tracker that summarizes issuesand resolutions, include a pointer to it
•If the WG does not have consensus on thisdocument, you should not request publication
Question 1.f
Has anyone threatened an appeal or otherwise indicated extremediscontent? If so, please summarize the areas of conflict in separateemail messages to the Responsible Area Director. (It should be in aseparate email because this questionnaire is entered into the IDTracker.)
•This is a reminder to tell the AD about seriously contentiousissues or possible appeals.
•Note that issues of this nature should be raised in a separatenote to the AD (not the Secretariat).
•Do not assume that the AD knows about whatever hashappened in the WG… Err on the side of too muchcommunication in these situations.
Question 1.g
Has the Document Shepherd personally verified that thedocument satisfies all ID nits? (See http://www.ietf.org/ID-Checklist.html and http://tools.ietf.org/tools/idnits/). Boilerplatechecks are not enough; this check needs to be thorough. Hasthe document met all formal review criteria it needs to, such asthe MIB Doctor, media type and URI type reviews?
•You MUST personally run the nits tool and check for compliancewith the checklist
•You should be embarrassed if your AD or other IESG membersfind nits in your documents
Question 1.h
Has the document split its references into normative andinformative? Are there normative references to documents thatare not ready for advancement or are otherwise in an unclearstate? If such normative references exist, what is the strategyfor their completion? Are there normative references that aredownward references, as described in [RFC3967]? If so, listthese downward references to support the Area Director in theLast Call procedure for them [RFC3967].
•This is to prevent documents from blocking on references afterapproval
•Downref specifics may be changing, but will not remove thisresponsibility
Question 1.i
Has the Document Shepherd verified that the document IANAconsideration section exists and is consistent with the body ofthe document? If the document specifies protocol extensions,are reservations requested in appropriate IANA registries? Arethe IANA registries clearly identified? If the document creates anew registry, does it define the proposed initial contents of theregistry and an allocation procedure for future registrations?Does it suggest a reasonable name for the new registry? See[RFC2434]. If the document describes an Expert Reviewprocess has Shepherd conferred with the Responsible AreaDirector so that the IESG can appoint the needed Expert duringthe IESG Evaluation?
•All document shepherds should read and understand RFC2434.
Question 1.j
Has the Document Shepherd verified that sections ofthe document that are written in a formal language,such as XML code, BNF rules, MIB definitions, etc.,validate correctly in an automated checker?
•You MUST personally run whatever automatedcheckers apply to your document
Question 1.k
The IESG approval announcement includes a DocumentAnnouncement Write-Up. Please provide such a DocumentAnnouncement Write-Up. Recent examples can be found in the"Action" announcements for approved documents. Theapproval announcement contains the following sections:
•This write-up will be included in the IESG ballot andin the document approval announcement
–It should be complete, insightful, professional, and meaningful topeople who have not read the document
Question 1.k (Cont.)
Technical Summary
Relevant content can frequently be found in the abstractand/or introduction of the document. If not, this may be anindication that there are deficiencies in the abstract orintroduction.
•In most cases, you can just copy the abstract for thissection.
–May want to shorten/summarize longer abstracts.
Question 1.k (Cont.)
Working Group Summary
Was there anything in WG process that is worth noting? Forexample, was there controversy about particular points or werethere decisions where the consensus was particularly rough?
•This is public information about the WG process.
•In many cases, this section simply says:
“This document is a work item of the Foo WG. The Foo WGhas consensus to publish this document as a <Info, PS…>RFC.”
Question 1.k (Cont.)
Document QualityAre there existing implementations of the protocol? Have asignificant number of vendors indicated their plan to implementthe specification? Are there any reviewers thatmerit special mention as having done a thorough review, e.g.,one that resulted in important changes or a conclusion that thedocument had no substantive issues? If there was a MIBDoctor, Media Type or other expert review, what was its course(briefly)? In the case of a Media Type review, on what date wasthe request posted?
•Give credit where credit is due
Question 1.k (Cont.)
Personnel
Who is the Document Shepherd for this document? Who is theResponsible Area Director?
•Something like this:
“This document was shepherded by <your name>. It wasreviewed for the IESG by <responsible AD>.”
AD Evaluation
•During this stage, the responsible AD willreview the document to determine if it isready for IESG review
–AD may return comments
–AD may request review from specific groups,which may result in comments
–Shepherd must ensure that there is a response toevery comment, even if no changes are required
–Shepherd must ensure that this stage istransparent and that the WG is aware of andagrees with all substantive changes made atthis stage
IETF Last Call
•Standards track documents and BCPs requirean IETF-wide Last Call
–The responsible AD sends the document to IETFLast Call
–Individuals and review groups may respond withcomments
–Shepherd must ensure that there is a response toevery comment, even if no changes are required
–Shepherd must ensure that this stage istransparent and that the WG is aware of andagrees with all substantive changes made atthis stage
IESG Evaluation
•IESG will review the document and return feedback
–DISCUSSes are blocking issues
–COMMENTs are non-blocking
•Shepherd must ensure that all discusses areresolved, and that a response is sent to allcomments, whether or not changes are required
–May require serving as a moderator between editor(s) or WGand IESG member(s)
•Shepherd must ensure that this stage is transparentand that the WG is aware of and agrees with allsubstantive changes made at this stage
IANA and RFC Editor
•IANA reviews document with IANA considerationsduring IETF LC
–May send questions about IANA actions
–These questions must be answered to IANA’s satisfactionbefore the document will be approved
•RFC Editor AUTH48 period may require shepherding
–Finding editors and getting them to respond
–Reviewing proposed AUTH48 changes
•Shepherd must ensure that these stages aretransparent and that the WG is aware of and agreeswith all substantive changes made at these stages
Conclusions
•Being a PROTO Shepherd is a lot ofwork!
–Yes, but it is all work that has to be done
•Previously, ADs did this work for all of theirWGs
–Having WG Chairs do this work scalesbetter
–And, it results in better WG visibility andtransparency throughout the process!!
Questions?
Questions on mechanics of theprocess? Please save generaldiscussion for next section.