GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools

Problem, Formatting or Query -  Send Feedback

Was this page helpful?-10+1


rfc:rfc4858

Network Working Group H. Levkowetz Request for Comments: 4858 Ericsson Category: Informational D. Meyer

                                            Cisco/University of Oregon
                                                             L. Eggert
                                                                 Nokia
                                                             A. Mankin
                                                              May 2007
  Document Shepherding from Working Group Last Call to Publication

Status of This Memo

 This memo provides information for the Internet community.  It does
 not specify an Internet standard of any kind.  Distribution of this
 memo is unlimited.

Copyright Notice

 Copyright (C) The IETF Trust (2007).

Abstract

 This document describes methodologies that have been designed to
 improve and facilitate IETF document flow processing.  It specifies a
 set of procedures under which a working group chair or secretary
 serves as the primary Document Shepherd for a document that has been
 submitted to the IESG for publication.  Before this, the Area
 Director responsible for the working group has traditionally filled
 the shepherding role.

Levkowetz, et al. Informational [Page 1] RFC 4858 Document Shepherding to Publication May 2007

Table of Contents

 1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
 2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  4
 3.  Process Description  . . . . . . . . . . . . . . . . . . . . .  4
   3.1.  Document Shepherd Write-Up . . . . . . . . . . . . . . . .  5
   3.2.  Document Shepherding during AD Evaluation  . . . . . . . .  9
   3.3.  Document Shepherding during IESG Evaluation  . . . . . . . 10
 4.  Shepherding the Document's IANA Actions  . . . . . . . . . . . 13
 5.  Document Shepherding after IESG Approval . . . . . . . . . . . 14
 6.  When Not to Use the Document Shepherding Process . . . . . . . 15
 7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 16
 8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
 9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 16
 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
   10.1. Normative References . . . . . . . . . . . . . . . . . . . 17
   10.2. Informative References . . . . . . . . . . . . . . . . . . 17
 Appendix A.  Example Document Announcement Write-Ups . . . . . . . 18
   A.1.  Example Document Announcement Write-Up for
         draft-ietf-avt-rtp-midi-format . . . . . . . . . . . . . . 18
   A.2.  Example Document Announcement Write-Up for
         draft-ietf-imss-ip-over-fibre-channel  . . . . . . . . . . 19

Levkowetz, et al. Informational [Page 2] RFC 4858 Document Shepherding to Publication May 2007

1. Introduction

 Early in 2004, the IESG undertook several experiments aimed at
 evaluating whether any of the proposed changes to the IETF document
 flow process would yield qualitative improvements in document
 throughput and quality.  One such experiment, referred to as the
 "PROTO process" or "PROTO" (because it was created by the "PROcess
 and TOols" or PROTO [PROTO] team), is a set of methodologies designed
 to involve working group chairs or secretaries more directly in their
 documents' approval life cycle.  In particular, the PROTO team
 focused on improvements to the part of a document's life cycle that
 occurs after the working group and document editor have forwarded it
 to the IESG for publication.
 By the end of 2004, the IESG had evaluated the utility of the PROTO
 methodologies based on data obtained through several pilot projects
 that had run throughout the year, and subsequently decided to adopt
 the PROTO process for all documents and working groups.  This
 document describes this process.
 The methodologies developed and piloted by the PROTO team focus on
 the working group chair or secretary as the primary Document
 Shepherd.  The primary objective of this document shepherding process
 is to improve document-processing throughput and document quality by
 enabling a partnership between the Responsible Area Director and the
 Document Shepherd.  In particular, this partnership has the explicit
 goal of enfranchising the Document Shepherd while at the same time
 offloading a specific part of the follow-up work that has
 traditionally been responsibility of the Responsible Area Director.
 The Responsible Area Director has tens or many tens of documents to
 follow, while the Document Shepherd has only a few at a time.
 Flowing the responsibility to the working group level can ensure more
 attention and more timely response.
 Consequently, the document shepherding process includes follow-up
 work during all document-processing stages after Working Group Last
 Call, i.e., during AD Evaluation of a document, during IESG
 Evaluation, and during post-approval processing by IANA and the RFC
 Editor.  In these stages, it is the responsibility of the Document
 Shepherd to track and follow up on feedback received on a document
 from all relevant parties.
 The Document Shepherd is usually a chair of the working group that
 has produced the document.  In consultation with the Responsible Area
 Director, the chairs may instead decide to appoint the working group
 secretary as the responsible Document Shepherd.

Levkowetz, et al. Informational [Page 3] RFC 4858 Document Shepherding to Publication May 2007

2. Terminology

 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 document are to be interpreted as described in BCP 14, RFC 2119
 [RFC2119].

3. Process Description

 The document shepherding process consists of the following tasks:
 o  Providing the Document Shepherd Write-Up accompanying a document
    that is forwarded to the IESG when publication is requested, as
    described in Section 3.1.
 o  During AD Evaluation of the document by the Responsible Area
    Director, managing the discussion between the editors, the working
    group, and the Responsible Area Director, as described in
    Section 3.2.
 o  During an IETF Last Call, if performed for the shepherded
    document, following up on community feedback and review comments.
 o  During IESG Evaluation, following up on all IESG feedback
    ("DISCUSS" and "COMMENT" items) related to the shepherded
    document, as described in Section 3.3.
 o  Following up on IANA and RFC Editor requests as described in
    Section 4 and Section 5.
 The shepherd must keep the document moving forward, communicating
 about it with parties who review and comment on it.  The shepherd
 must obtain the working group's consensus for any substantive
 proposed changes.  The shepherd is the leader for the document and
 for the working group, and maintains a critical and technical
 perspective.  In summary, the Document Shepherd continues to care for
 a shepherded document during its post-WG lifetime just as he or she
 has done while responsible for the document in the working group.
 Before any document shepherding takes place, a single Document
 Shepherd MUST be identified for a document (he or she will be named
 in the Document Shepherd Write-Up).  Frequently, the chairs and the
 Responsible Area Director will decide that the working group will
 adopt the PROTO process for all their future documents.  After that
 decision, the chairs, in consultation with the Responsible Area
 Director, decide on who should act as Document Shepherd for any given
 document.  This is typically and by default one of the chairs of the
 working group.  In consultation with the Responsible Area Director,

Levkowetz, et al. Informational [Page 4] RFC 4858 Document Shepherding to Publication May 2007

 the chairs MAY also decide to appoint the working group secretary as
 Document Shepherd for a given document.  The Document Shepherd SHOULD
 NOT be an editor of the shepherded document.
 It is intended that the Document Shepherd role be filled by one
 person during the entire shepherding process.  However, situations
 may occur when the Document Shepherd role may be reassigned to
 different persons during the lifetime of a document.  It is up to the
 chairs and Responsible Area Director to identify situations when this
 may become necessary, and then consult to appoint a new Document
 Shepherd.
 It is important to note that the document shepherding process only
 applies to documents that are the product of a working group.  It
 does not apply to documents that originate elsewhere.  Additionally,
 Section 6 discusses other instances in which the document shepherding
 process does not apply.

3.1. Document Shepherd Write-Up

 When a working group decides that a document is ready for submission
 to the IESG for publication, it is the task of the Document Shepherd
 to complete a "Document Shepherd Write-Up" for the document.
 There are two parts to this task.  First, the Document Shepherd
 answers questions (1.a) to (1.j) below to give the Responsible Area
 Director insight into the working group process that applied to this
 document.  Note that while these questions may appear redundant in
 some cases, they are written to elicit information that the
 Responsible Area Director must be aware of (to this end, pointers to
 relevant entries in the WG archive are helpful).  The goal here is to
 inform the Responsible Area Director about any issues that may have
 come up in IETF meetings, on the mailing list, or in private
 communication that they should be aware of prior to IESG Evaluation
 of the shepherded document.  Any significant issues mentioned in the
 questionnaire will probably lead to a follow-up discussion with the
 Responsible Area Director.
 The second part of the task is to prepare the "Document Announcement
 Write-Up" that is input both to the ballot for the IESG telechat and
 to the eventual IETF-wide announcement message.  Item number (1.k)
 describes the elements of the Document Announcement Write-Up.
 Some examples of Document Announcement Write-Ups are included in
 Appendix A, and there are many more examples with subject lines such
 as "Protocol Action" and "Document Action" in the IETF-announce
 mailing list archive.

Levkowetz, et al. Informational [Page 5] RFC 4858 Document Shepherding to Publication May 2007

 The initial template for the Document Shepherd Write-Up is included
 below, but changes are expected over time.  The latest version of
 this template is available from the IESG section of the IETF web
 site.
 (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?
 (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?
 (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?
 (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.
 (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?
 (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.)
 (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

Levkowetz, et al. Informational [Page 6] RFC 4858 Document Shepherding to Publication May 2007

        met all formal review criteria it needs to, such as the MIB
        Doctor, media type, and URI type reviews?  If the document
        does not already indicate its intended status at the top of
        the first page, please indicate the intended status here.
 (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].
 (1.i)  Has the Document Shepherd verified that the document's IANA
        Considerations 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 the Document
        Shepherd conferred with the Responsible Area Director so that
        the IESG can appoint the needed Expert during IESG Evaluation?
 (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?
 (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:
        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.

Levkowetz, et al. Informational [Page 7] RFC 4858 Document Shepherding to Publication May 2007

        Working Group Summary
           Was there anything in the WG process that is worth noting?
           For example, was there controversy about particular points
           or were there decisions where the consensus was
           particularly rough?
        Document Quality
           Are there existing implementations of the protocol?  Have a
           significant number of vendors indicated their plan to
           implement the specification?  Are there any reviewers that
           merit 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?
        Personnel
           Who is the Document Shepherd for this document?  Who is the
           Responsible Area Director?  If the document requires IANA
           experts(s), insert 'The IANA Expert(s) for the registries
           in this document are <TO BE ADDED BY THE AD>.'
 The Document Shepherd MUST send the Document Shepherd Write-Up to the
 Responsible Area Director and iesg-secretary@ietf.org together with
 the request to publish the document.  The Document Shepherd SHOULD
 also send the entire Document Shepherd Write-Up to the working group
 mailing list.  If the Document Shepherd feels that information which
 may prove to be sensitive, may lead to possible appeals, or is
 personal needs to be written up, it SHOULD be sent in direct email to
 the Responsible Area Director, because the Document Shepherd Write-Up
 is published openly in the ID Tracker.  Question (1.f) of the
 Write-Up covers any material of this nature and specifies this more
 confidential handling.
 The Document Shepherd Write-Up is entered into the ID Tracker
 [IDTRACKER] as a "Comment".  The name and email address of the
 Document Shepherd are entered into the ID Tracker, currently as a
 "Brief Note" (this may change in the future).  The email address of
 the Document Shepherd MUST also be added to the "State or Version
 Change Notice To" field (typically the email addresses of all working
 group chairs, authors, and the secretary will be added).
 Entering the name and email of the Document Shepherd into the ID
 Tracker is REQUIRED to ensure that he or she will be copied on the
 email exchange between the editors, chairs, the IESG, the IESG
 secretariat, IANA, and the RFC Editor during the review and approval
 process.  There are still manual steps required for these parties to

Levkowetz, et al. Informational [Page 8] RFC 4858 Document Shepherding to Publication May 2007

 ensure that they include the Document Shepherd, but it is hoped that
 in the future, automated tools will ensure that Document Shepherds
 (and others) receive necessary communications.
 The contact information for the Document Shepherd is also important
 for the Gen-ART team [GEN-ART], area directorates, and other review
 teams, so they can know to whom to address reviews, in addition to
 the Responsible Area Director.

3.2. Document Shepherding during AD Evaluation

 The steps for document shepherding during AD Evaluation are as
 follows:
 (2.a)  The Responsible Area Director reads, evaluates, and comments
        on the document, as is the case when not using the document
        shepherding process.  If the Responsible Area Director
        determines that the document is ready for IESG Evaluation, he
        or she indicates this to the Document Shepherd and the
        document shepherding process continues as described in
        Section 3.3.
 (2.b)  If the Responsible Area Director has identified issues with a
        document that must be addressed before IESG Evaluation can
        commence, he or she sends a full evaluation to the Document
        Shepherd and SHOULD also enter the review into the ID Tracker.
 (2.c)  The Document Shepherd reads the AD Evaluation comments, making
        very certain that all comments are understood, so that it is
        possible to follow up on them with the editors and working
        group.  If there is some uncertainty as to what is requested,
        this SHOULD be resolved with the Responsible Area Director.
 (2.d)  The Document Shepherd sends the AD Evaluation comments to the
        editors and to the working group mailing list, in order to
        have a permanent record of the comments.  It is RECOMMENDED
        that the Document Shepherd solicit from the editors an
        estimate on when the required changes will be completed and a
        revised document can be expected.  Working groups that use
        issue tracking SHOULD also record the issues (and eventually
        their resolution) in their issue tracker.
 (2.e)  During the production of a revised document that addresses the
        AD Evaluation comments, it is RECOMMENDED that the editors
        keep a list showing how each comment was addressed and what
        the revised text is.  It is RECOMMENDED that this list be
        forwarded to the Responsible Area Director together with the
        revised document.

Levkowetz, et al. Informational [Page 9] RFC 4858 Document Shepherding to Publication May 2007

 (2.f)  In the event that the editors or working group disagrees with
        a comment raised by the Responsible Area Director or has
        previously considered and dismissed the issue, the Document
        Shepherd MUST resolve the issue with the Responsible Area
        Director before a revised document can be submitted.
 (2.g)  The Document Shepherd iterates with the editors (and working
        group, if required) until all outstanding issues have been
        resolved and a revised document is available.  At this point,
        the Document Shepherd notifies the Responsible Area Director
        and provides him or her with the revised document, the summary
        of issues, and the resulting text changes.
 (2.h)  The Responsible Area Director verifies that the issues he or
        she found during AD Evaluation are resolved in the revised
        version of the document by starting the process described in
        this section at step (2.a).
 (2.i)  If the document underwent an IETF Last Call and the AD
        concludes that significant issues were raised during the Last
        Call, then steps (2.b) through (2.h) need to be applied
        addressing the Last Call issues.  This requires the
        Responsible Area Director to present to the Document Shepherd
        those Last Call issues raised only to the IESG.

3.3. Document Shepherding during IESG Evaluation

 During IESG Evaluation of a document, ADs can bring forward two kinds
 of remarks about a document: DISCUSS items and COMMENT items.  A
 DISCUSS blocks a document's approval process until it has been
 resolved; a COMMENT does not.  This section details the steps that a
 Document Shepherd takes to resolve any DISCUSS and COMMENT items
 brought forward against a shepherded document during IESG Evaluation.
 Note that DISCUSS and COMMENT items are occasionally written in a
 manner that makes their intent unclear.  In these cases, the Document
 Shepherd SHOULD start a discussion with the ADs who brought the items
 up to clarify their intent, keeping the Responsible Area Director
 informed.  If this fails to clarify the intent, the Responsible Area
 Director may need to work towards a clarification inside the IESG.
 (3.a)  Leading up to the IESG conference call, the Document Shepherd
        may see emails about the document from directorate reviewers
        on behalf of one or more ADs and also emailed copies of
        DISCUSS and COMMENT items entered into the ID Tracker.  The
        Document Shepherd SHOULD immediately begin to work on
        resolving DISCUSS and COMMENT items with the ADs who have
        raised them, keeping the Responsible Area Director copied on

Levkowetz, et al. Informational [Page 10] RFC 4858 Document Shepherding to Publication May 2007

        the email exchange, so that he or she is able to support the
        activity during the conference call.  When dealing with
        directorate reviews, the Document Shepherd MUST involve the
        ADs to whom these directorates report to ensure that these ADs
        consider the review comments that need resolving.
 (3.b)  Immediately following the conference call, when the document
        changes state from the "IESG Evaluation" state to one of the
        states requiring Document Shepherd action, e.g., "IESG
        Evaluation: Revised ID Needed" or "IESG Evaluation: AD
        Followup", the Document Shepherd will receive email.  A state
        of "AD Followup" typically signifies the Responsible Area
        Director's hope that a resolution may be possible through a
        continued discussion or (more usually) through a small set of
        changes as "Notes to the RFC Editor".
        Note that there may be very exceptional cases when DISCUSS
        items are registered after an IESG conference call.  In these
        cases, the AD who has raised the DISCUSS MUST notify the
        Document Shepherd about it.  (The notification facility in the
        ID Tracker is very convenient for this purpose and also for
        the cases where the DISCUSS and COMMENT items are updated
        after they are partially resolved.)
 (3.c)  The Document Shepherd then queries the ID Tracker to collect
        the remaining DISCUSS and COMMENT items raised against the
        document.  The Document Shepherd analyzes these items and
        initializes contact with the ADs who have placed them.  The
        Responsible Area Director MUST be copied on all correspondence
        related to active DISCUSS or COMMENT items.  This does not
        place the Responsible Area Director in the critical path
        towards a resolution, but should keep him or her informed
        about the state of the discussion.
        +-------+              +-------+               +-------+
        | (3.b) | -----------> | (3.c) | ------------> | (3.d) |
        +-------+  Comments    +-------+   Comments    +-------+
                   collected    /|\  |    understood
                                 |   |
                                 |   | Comments not fully understood
                                 |   | (Further AD/Document Shepherd
                                 |   |  discussion required)
                                 +---+
 (3.d)  The Document Shepherd then coordinates the resolution of
        DISCUSS and COMMENT items and builds a consistent
        interpretation of the comments.  This step is similar to much
        of the process described in Section 3.2.

Levkowetz, et al. Informational [Page 11] RFC 4858 Document Shepherding to Publication May 2007

        +-------+                  +-------+
        | (3.c) | ---------------> | (3.d) |
        +-------+    Consistent    +-------+
           /|\     interpretation      |
            |                          | Further AD/Document Shepherd
            |                          | discussion required
            +--------------------------+
 (3.e)  The Document Shepherd then communicates the DISCUSS and
        COMMENT items to the document editors and the working group,
        alerting them of any changes to the document that have
        accumulated during IESG processing, such as "Notes to the RFC
        Editor".  If any changes will be substantive, the Document
        Shepherd, in consultation with the Responsible Area Director,
        as during other stages, MUST confirm working group consensus
        or sometimes even IETF consensus.
 (3.f)  After the editors resolve the DISCUSS and COMMENT items, the
        Document Shepherd reviews the resulting new version of the
        document, which will be a revised document, a set of "Notes to
        the RFC Editor", or both, using his or her technical expertise
        to ensure that all raised DISCUSS and COMMENT issues have been
        resolved.
        Note that the Document Shepherd MAY also suggest resolutions
        to DISCUSS and COMMENT items, enter them into an issue
        tracker, or perform other steps to streamline the resolution
        of the evaluation comments.  It is very important to resolve
        the comments in a timely way, while the discussion is current
        for everyone involved.
 (3.g)  When the Document Shepherd is satisfied that the revised
        document addresses the evaluation comments, he or she
        communicates the resolution to the Responsible Area Director
        and the ADs that had raised the DISCUSS and COMMENT items.
 (3.h)  Each AD who had raised a DISCUSS checks whether the
        communicated resolution addresses his or her items.  If it
        does, the AD will clear the DISCUSS.  If it does not, the AD
        notifies the Document Shepherd and adds information to the ID
        Tracker explaining why the DISCUSS was not resolved.  The
        Document Shepherd informs the working group accordingly.
        (COMMENT items need not be checked and cleared, because they
        do not block the document, but ADs are encouraged to do so.)
        If a DISCUSS was not resolved to the satisfaction of the AD
        that has raised it or the Responsible Area Director, two
        possibilities exist:

Levkowetz, et al. Informational [Page 12] RFC 4858 Document Shepherding to Publication May 2007

        (a)  The process returns to step (3.d), or
        (b)  If no progress can be made on the resolution of the
             DISCUSS with the AD who has raised it, despite repeated
             clarifications and discussions, the Responsible Area
             Director should take over continued shepherding of the
             document.  Such a situation may be indicative of larger
             issues that the PROTO process was not designed to handle.
        Once the process above has cleared all DISCUSS items, document
        shepherding continues with step (3.i).
 (3.i)  The Responsible Area Director moves the document to the
        "Approved - Announcement to be sent" state in the ID Tracker.
        If he or she deems the changes to the revised document
        significant, there may be a new WG Last Call, or possibly a
        new IETF Last Call.  The document goes through a new full IESG
        Evaluation process if there is a new IETF Last Call.

4. Shepherding the Document's IANA Actions

 IETF working group documents often include considerations requiring
 actions by the IANA, such as creating a new registry or adding
 information to an existing registry, perhaps after consulting an
 IESG-appointed Expert.  Sometimes the Document Shepherd must keep
 track of certain IANA actions to be completed by the IESG, such as
 ratifying the appointment of a designated Expert called for in the
 IANA Considerations.  IANA-related processing may also include a
 specified type of Expert review, such as review of proposed MIME
 media types on the designated ietf-types mailing list.
 The IANA reviews IETF documents and requests responses at any or all
 of the following times: in response to IETF Last Call, during the
 IESG Evaluation review of the document, and at the time when the IANA
 performs actions in its web-based registry for the document, usually
 but not always after IESG approval of the document.  More details of
 the IANA process and IETF interaction are found in [RFC2434].
 At the time of this publication, RFC 2434 is under revision
 [RFC2434bis], and the updates are and will be of value to the
 Document Shepherd.  Note that the Document Shepherd MUST determine
 (by individual review and consultation with others) what is the most
 recent and the most applicable IANA information and guidance for his
 or her document, be it the overall guidance, or external documents in
 his or her area, or in other areas.  An example of an external
 document is [RFC4020].

Levkowetz, et al. Informational [Page 13] RFC 4858 Document Shepherding to Publication May 2007

 Whenever an IANA request comes, during whatever phase of the
 shepherding process, the requester from IANA MUST ensure that the
 Document Shepherd and the Responsible Area Director both receive the
 request.  The Document Shepherd is responsible for responding as
 rapidly as possible.  He or she should discuss requests that
 introduce any possible concerns with the working group.  The Document
 Shepherd and the Responsible Area Director may decide in consultation
 that an IANA request leads to a change that needs additional review
 or approval.
 In general, the Document Shepherd ensures that the IANA process
 completes, checks that the registry is correct and that the IANA
 Matrix (http://www.iana.org/numbers.html) is complete and consistent,
 and troubleshoots when all is not well.  At the end of IANA
 processing, the Document Shepherd should be sure that the RFC Editor
 has acknowledged IANA conclusion, i.e., that the handoff has been
 made.
 In summary, the task of shepherding the IANA actions is often
 overlooked, but is as important to coordinate and manage as all the
 other document reviews the Document Shepherd has managed.  As with
 those, the Document Shepherd contributes greatly to quality and
 timeliness of the document by effective and responsive shepherding of
 the IANA requests.

5. Document Shepherding after IESG Approval

 After the IESG Evaluation and resolution described in Section 3.3,
 the IESG approves the document, and the Responsible Area Director
 uses the ID Tracker to ask for any final changes to the Document
 Announcement Write-Up and for it to be issued.  The Document Shepherd
 may have some edits for the Responsible Area Director, such as minor
 "Notes to the RFC Editor", and this is the time to consult and
 provide them.
 The IESG approval announcement goes to the general community and to
 the RFC Editor, and now the Document Shepherd (identified in the
 Announcement Write-Up) continues to shepherd the document through its
 technical publication.  The RFC Editor currently makes a number of
 types of requests to the authors, Document Shepherd and Responsible
 Area Director.  The Document Shepherd SHOULD lead in responding to
 the RFC Editor and shepherd the document during the post-approval
 period to its publication.
 The RFC Editor request types include: editorial queries about
 dangling or missing informative and normative citations (good
 shepherding should try to catch these earlier, but they happen);
 requests for the document source (e.g., XML or nroff); occasional

Levkowetz, et al. Informational [Page 14] RFC 4858 Document Shepherding to Publication May 2007

 technical comments; and copy-edits for review and close scrutiny by
 the authors (AUTH48).  For the latter, the Document Shepherd SHOULD
 lead in checking that copy-edits have in no case affected a consensus
 wording of the working group that prepared the document, and SHOULD
 bring speed to this checking by multiple coauthors.  The Document
 Shepherd also consults with the Responsible Area Director on
 reviewing proposed post-approval changes to the document by any
 author.  These may require Area Director approval, and they often
 need to be presented to the working group for consent if not a full
 consensus procedure.
 As in other phases of document shepherding, the Document Shepherd
 provides attentiveness and timeliness by serving as the informed
 representative of the document and helping its advancement and its
 integrity.

6. When Not to Use the Document Shepherding Process

 As mentioned in Section 3, the Document Shepherd SHOULD NOT be an
 editor of the shepherded document.  If this cannot be avoided by
 making another working group chair or secretary the Document
 Shepherd, the document shepherding process SHOULD NOT be used.  There
 are several other cases in which the document shepherding process
 SHOULD NOT be used.  These include:
 1.  Cases where the Document Shepherd is the primary author or editor
     of a large percentage of the documents produced by the working
     group.
 2.  Cases where the Responsible Area Director expects communication
     difficulties with the Document Shepherd (either due to
     experience, strong views stated by the Document Shepherd, or
     other issues).
 3.  Cases where the working group itself is either very old, losing
     energy, or winding down (i.e., cases where it would not be
     productive to initiate new processes or procedures).
 Finally, note that other cases exist in which using the document
 shepherding process may not be productive.  The final determination
 as to whether or not to use the document shepherding process is left
 to the Responsible Area Director.  If the document shepherding
 process is not used, the Responsible Area Director acts as Document
 Shepherd, per the existing procedures of shepherding by Area
 Directors.

Levkowetz, et al. Informational [Page 15] RFC 4858 Document Shepherding to Publication May 2007

7. Security Considerations

 This document specifies a change to IETF document-processing
 procedures.  As such, it neither raises nor considers protocol-
 specific security issues.

8. IANA Considerations

 This document creates no new requirements on IANA namespaces or other
 IANA requirements.

9. Acknowledgments

 This document is the product of the PROTO team, which includes the
 authors as well as Bill Fenner, Barbara Fuller, and Margaret
 Wasserman.  Aaron Falk worked actively in PROTO until the start of
 2006 and worked on earlier versions of the document.
 The Document Shepherd Write-Up originated in an idea by John Klensin.
 Thomas Narten and Margaret Wasserman implemented it for the entire
 Internet Area, and their template was the basis of the version used
 today.
 Colin Perkins wrote the original Document Announcement Write-Up for
 draft-ietf-avt-rtp-midi-format included in Appendix A.1.  David Black
 wrote the original Document Announcement Write-Up for
 draft-ietf-imss-ip-over-fibre-channel included in Appendix A.2.  Both
 original announcements have been modified to reflect changes to the
 Document Announcement Write-Up template since they were written.
 Frank Ellermann and Olafur Gudmundsson have suggested improvements to
 the document during IETF Last Call.

Levkowetz, et al. Informational [Page 16] RFC 4858 Document Shepherding to Publication May 2007

10. References

10.1. Normative References

 [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

10.2. Informative References

 [RFC4020]     Kompella, K. and A. Zinin, "Early IANA Allocation of
               Standards Track Code Points", BCP 100, RFC 4020,
               February 2005.
 [RFC2434]     Narten, T. and H. Alvestrand, "Guidelines for Writing
               an IANA Considerations Section in RFCs", BCP 26,
               RFC 2434, October 1998.
 [RFC3967]     Bush, R. and T. Narten, "Clarifying when Standards
               Track Documents may Refer Normatively to Documents at a
               Lower Level", BCP 97, RFC 3967, December 2004.
 [RFC2434bis]  Narten, T. and H. Alvestrand, "Guidelines for Writing
               an IANA Considerations Section in RFCs", Work in
               Progress, March 2007.
 [IDTRACKER]   "The IETF Internet-Draft Tracker", Web
               Application: https://datatracker.ietf.org/, 2002.
 [PROTO]       "The IESG PROcess and TOols (PROTO) Team", Web
               Page: http://psg.com/~mrw/PROTO-Team, 2004.
 [GEN-ART]     "The General Area Review Team (GEN-ART)", Web Page:
               http://www.alvestrand.no/ietf/gen/
               review-guidelines.html, 2005.

Levkowetz, et al. Informational [Page 17] RFC 4858 Document Shepherding to Publication May 2007

Appendix A. Example Document Announcement Write-Ups

 This appendix includes two examples of Document Announcement Write-
 Ups.  Many more examples with Subject lines such as "Protocol Action"
 and "Document Action" can be found in the IETF-announce mailing list
 archive.

A.1. Example Document Announcement Write-Up for

    draft-ietf-avt-rtp-midi-format
 Technical Summary
    These documents define the RTP Payload format for MIDI (Musical
    Instrument Digital Interface), and additional guidelines on
    implementation specifically concerning the timing of reception and
    transmission for best performance in different applications.  MIDI
    is a real-time media, which however is brittle to losses and
    errors.  Therefore the RTP payload format defines recovery
    journals as a way of avoiding persistent audible errors, and
    discusses congestion control handling for these journals.
    The RTP payload for MIDI encodes the broad range of MIDI commands.
    The format is suitable for interactive applications (such as
    network musical performance) and content-delivery (such as file
    streaming).
 Working Group Summary
    There is consensus in the WG to publish these documents.
 Document Quality
    This RTP Payload format has been implemented during the
    development of the specification and successfully tested over an
    IP network between two remote sites, thus showing that the
    technical solution is successfully working.  It has been reviewed
    by the MIDI Manufacturers Association and their comments have been
    addressed.
 Personnel
    Magnus Westerlund and Colin Perkins jointly shepherded this
    document.  Allison Mankin reviewed the document for the IESG,
    including a careful review with the editor of the media types, in
    parallel with ietf-types list review requested on 2006-01-08,
    which raised no issues.

Levkowetz, et al. Informational [Page 18] RFC 4858 Document Shepherding to Publication May 2007

A.2. Example Document Announcement Write-Up for

    draft-ietf-imss-ip-over-fibre-channel
 Technical Summary
    This document specifies the encapsulation of IPv6, IPv4 and ARP
    packets over Fibre Channel.  This document also specifies the
    methods for forming IPv6 link-local addresses and statelessly
    autoconfigured IPv6 addresses on Fibre Channel networks, and a
    mechanism to perform IPv4 address resolution over Fibre Channel
    networks.  This document (when published as RFC) obsoletes RFC2625
    and RFC3831.
 Working Group Summary
    This document has been reviewed by Fibre Channel experts in
    Technical Committee T11 (Fibre Channel standards organization) in
    addition to members of the IMSS WG.  There is solid support for
    this document both in the WG and from T11.
 Document Quality
    This document replaces and consolidates two separate RFCs on IPv4
    over Fibre Channel (RFC 2625) and IPv6 over Fibre Channel (RFC
    3831).  Most of its technical content is unchanged from those
    RFCs.  The technical changes that have been made are primarily
    based on implementation experience.
 Personnel
    The protocol has been reviewed for the IESG by David L. Black (WG
    chair).  Bert Wijnen has reviewed this document for the IESG.  In
    addition, Brian Haberman has done a review for the INT Area as
    requested by WG-chair (David Black) via Margaret Wasserman.

Levkowetz, et al. Informational [Page 19] RFC 4858 Document Shepherding to Publication May 2007

Authors' Addresses

 Henrik Levkowetz
 Torsgatan 71
 Stockholm  S-113 37
 Sweden
 Phone: +46 708 32 16 08
 EMail: henrik@levkowetz.com
 David Meyer
 1225 Kincaid St
 Eugene, OR  97403
 USA
 Phone: +1 541 346 1747
 EMail: dmm@1-4-5.net
 Lars Eggert
 Nokia Research Center
 P.O. Box 407
 Nokia Group  00045
 Finland
 Phone: +49 50 48 24461
 EMail: lars.eggert@nokia.com
 URI:   http://research.nokia.com/people/lars_eggert
 Allison Mankin
 Phone: +1-301-728-7199
 EMail: mankin@psg.com
 URI:   http://www.psg.com/~mankin

Levkowetz, et al. Informational [Page 20] RFC 4858 Document Shepherding to Publication May 2007

Full Copyright Statement

 Copyright (C) The IETF Trust (2007).
 This document is subject to the rights, licenses and restrictions
 contained in BCP 78, and except as set forth therein, the authors
 retain all their rights.
 This document and the information contained herein are provided on an
 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

 The IETF takes no position regarding the validity or scope of any
 Intellectual Property Rights or other rights that might be claimed to
 pertain to the implementation or use of the technology described in
 this document or the extent to which any license under such rights
 might or might not be available; nor does it represent that it has
 made any independent effort to identify any such rights.  Information
 on the procedures with respect to rights in RFC documents can be
 found in BCP 78 and BCP 79.
 Copies of IPR disclosures made to the IETF Secretariat and any
 assurances of licenses to be made available, or the result of an
 attempt made to obtain a general license or permission for the use of
 such proprietary rights by implementers or users of this
 specification can be obtained from the IETF on-line IPR repository at
 http://www.ietf.org/ipr.
 The IETF invites any interested party to bring to its attention any
 copyrights, patents or patent applications, or other proprietary
 rights that may cover technology that may be required to implement
 this standard.  Please address the information to the IETF at
 ietf-ipr@ietf.org.

Acknowledgement

 Funding for the RFC Editor function is currently provided by the
 Internet Society.

Levkowetz, et al. Informational [Page 21]

/data/webs/external/dokuwiki/data/pages/rfc/rfc4858.txt · Last modified: 2007/05/02 02:03 (external edit)