A Practical Guide toPROTO Shepherding

WG Chairs Training Lunch

IETF68 Prague

Margaret Wasserman

margaret@thingmagic.com

PROTO Goals

• Improve efficiency and transparency of the final stages of the IETF process– Offload work from the IESG– Maintain WG visibility and document

ownership through RFC publication

PROTO History

• Started as an experiment about three years ago

• Now adopted IETF-wide in all areas– Some WGs or documents may be handled

differently at AD’s discretion

Definitive References

• Document Shepherding from Working Group Last Call to Publication– draft-ietf-proto-wgchair-doc-shepherding-

09.txt– Approved for publication as an Info RFC

• Requirements on I-D Tracker Extensions for Working Group Chairs– draft-ietf-proto-wgchair-tracker-ext-03.txt

What is a PROTO Shepherd?

• The person responsible for shepherding an IETF document through the last stages of the IETF process– From Publication Requested through RFC

Publication– Usually a WG Chair or Secretary– Not the editor or author of the document

• Responsible for driving progress and maintaining WG visibility and transparency during 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 split between WG co-chairs– Divide up documents when accepted as WG work

items– Shepherd drives document from WG acceptance

through RFC publication

Shepherding Tasks

• Provide the Document Shepherd Write-Up when publication is requested

• During AD Evaluation, manage discussion between editors, working group, and the AD

• During an IETF Last Call, follow up on community feedback and review comments.

• During IESG evaluation, following up on all IESG feedback

• Follow up on IANA and RFC Editor requests in the post-approval stages

Document Shepherd Write-Up

• Answers questions (items 1.a to 1.j) to give AD insight into the WG process

• Provides a Document Announcement Write-Up (item 1.k) that is included in the IESG ballot and sent to the IETF when the document is approved for publication

• MUST be sent with publication request to the Secretariat (iesg-secretary@ietf.org) and the Responsible AD

Purpose of the Write-Up

• Encourages the Shepherd to take personal responsibility for determining that the proper WG process has been followed

• Communicates history, issues and concerns to the AD

Question 1.a

Who is the Document Shepherd for this document? Has the Document Shepherd personally reviewed this version of the document and, in particular, does he or she believe this version is ready for forwarding to the IESG for publication?

• Name one person (you) who will be shepherding this work.

• You MUST personally review this document– ADs will bounce back documents if you answer “no”.

• You SHOULD be believe that this version is ready for publication– If not, you need to be very clear with your AD about why you are

submitting it for publication over your own objections

Question 1.b

Has the document had adequate review both from key WG members and from key non-WG members? Does the Document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

• Again, you SHOULD answer yes to this question– If the document has not been adequately reviewed, get it

reviewed before submitting it for publication– If you do have concerns, be clear about why you are

forwarding it for publication, anyway

Question 1.c

Does the Document Shepherd have concerns that the document needs more review from a particular or broader perspective, e.g., security, operational complexity, someone familiar with AAA, internationalization or XML?

• This is your chance to ask the AD for help in getting wider IETF review for your document

• If you include requests in this area and don’t see any action from the AD, follow up with the AD to get information about how to get this review

• It remains your responsibility to make sure that the document is adequately reviewed before publication

Question 1.d

Does the Document Shepherd have any specific concerns or issues with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here. Has an IPR disclosure related to this document been filed? If so, please include a reference to the disclosure and summarize the WG discussion and conclusion on this issue.

• This is your opportunity to raise issues where you would like the AD to check if the right decisions were made. Also to alert the AD to issues that may be raised in IETF LC.

Question 1.e

How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

• Provide a frank summary of the WG consensus process

• If there is an issue tracker that summarizes issues and resolutions, include a pointer to it

• If the WG does not have consensus on this document, you should not request publication

Question 1.f

Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is entered into the ID Tracker.)

• This is a reminder to tell the AD about seriously contentious issues or possible appeals.

• Note that issues of this nature should be raised in a separate note to the AD (not the Secretariat).

• Do not assume that the AD knows about whatever has happened in the WG… Err on the side of too much communication in these situations.

Question 1.g

Has the Document Shepherd personally verified that the document satisfies all ID nits? (See http://www.ietf.org/ID-Checklist.html and http://tools.ietf.org/tools/idnits/). Boilerplate checks are not enough; this check needs to be thorough. Has the document met all formal review criteria it needs to, such as the MIB Doctor, media type and URI type reviews?

• You MUST personally run the nits tool and check for compliance with the checklist

• You should be embarrassed if your AD or other IESG members find nits in your documents

Question 1.h

Has the document split its references into normative and informative? Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the strategy for their completion? Are there normative references that are downward references, as described in [RFC3967]? If so, list these downward references to support the Area Director in the Last Call procedure for them [RFC3967].

• This is to prevent documents from blocking on references after approval

• Downref specifics may be changing, but will not remove this responsibility

Question 1.i

Has the Document Shepherd verified that the document IANA consideration section exists and is consistent with the body of the document? If the document specifies protocol extensions, are reservations requested in appropriate IANA registries? Are the IANA registries clearly identified? If the document creates a new registry, does it define the proposed initial contents of the registry 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 Review process has Shepherd conferred with the Responsible Area Director so that the IESG can appoint the needed Expert during the IESG Evaluation?

• All document shepherds should read and understand RFC2434.

Question 1.j

Has the Document Shepherd verified that sections of the 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 automated checkers apply to your document

• You can find the applicable tools here: http://tools.ietf.org/inventory/verif-tools

Question 1.k

The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the"Action" announcements for approved documents. The approval announcement contains the following sections:

• This write-up will be included in the IESG ballot and in the document approval announcement– It should be complete, insightful, professional, and meaningful to

people who have not read the document

Question 1.k (Cont.)

Technical Summary

Relevant content can frequently be found in the abstract and/or introduction of the document. If not, this may be an indication that there are deficiencies in the abstract or introduction.

• In most cases, you can just copy the abstract for this section. – May want to shorten/summarize longer abstracts.

Question 1.k (Cont.)

Working Group Summary

Was there anything in WG process that is worth noting? For example, was there controversy about particular points or were there 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 WG has consensus to publish this document as a <Info, PS…> RFC.”

Question 1.k (Cont.)

Document QualityAre there existing implementations of the protocol? Have a significant number of vendors indicated their plan to implement the 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 the document had no substantive issues? If there was a MIB Doctor, Media Type or other expert review, what was its course (briefly)? In the case of a Media Type review, on what date was the request posted?

• Give credit where credit is due

Question 1.k (Cont.)

Personnel

Who is the Document Shepherd for this document? Who is the Responsible Area Director?

• Something like this:“This document was shepherded by <your name>. It was

reviewed for the IESG by <responsible AD>.”

AD Evaluation

• During this stage, the responsible AD will review the document to determine if it is ready 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 to

every comment, even if no changes are required– Shepherd must ensure that this stage is transparent

and that the WG is aware of and agrees with all substantive changes made at this stage

IETF Last Call

• Standards track documents and BCPs require an IETF-wide Last Call– The responsible AD sends the document to IETF

Last Call– Individuals and review groups may respond with

comments– Shepherd must ensure that there is a response to

every comment, even if no changes are required– Shepherd must ensure that this stage is transparent

and that the WG is aware of and agrees with all substantive changes made at this 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 are resolved, and that a response is sent to all comments, whether or not changes are required– May require serving as a moderator between editor(s) or

WG and IESG member(s)

• Shepherd must ensure that this stage is transparent and that the WG is aware of and agrees with all substantive changes made at this stage

IANA and RFC Editor

• IANA reviews document with IANA considerations during IETF LC– May send questions about IANA actions– These questions must be answered to IANA’s satisfaction

before 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 are transparent and that the WG is aware of and agrees with all substantive changes made at these stages

Conclusions

• Being a PROTO Shepherd is a lot of work!– Yes, but it is all work that has to be done

• Previously, ADs did this work for all of their WGs

– Having WG Chairs do this work scales better

– And, it results in better WG visibility and transparency throughout the process!!

Questions?

Questions on mechanics of the process? Please save general

discussion for next section.