Difference between revisions of "IAB Document Process"
(Move from private wiki)
Revision as of 06:04, 7 November 2019
IAB Document Process
IAB Stream RFCs (RFC 4845) are seen as documents that speak 'for the IAB'. The quality of those documents reflects on the IAB as an institution.
In order to improve the understanding and create a common ground for IAB document processing we will attempt use the following steps for adoption, review, and tracking IAB documents.
This is not a full fledged process flow and there are a few places where there is the possibility for the process to go astray. It is the intention for this document to be a living document.
There are three types of IAB documents:
- Documents that reflect IAB consensus on the content, and are published in the IAB Stream (RFC 4845) as Informational documents.
- Documents that do not necessarily reflect IAB consensus on the content, other than that it accurately summarizes the result of a community discussion (e.g., a workshop) sponsored by the IAB. These are published in the IAB Stream as Informational documents.
- Documents that reflect IAB consensus on the content but are intended as Best Current Practice. These must be published in the IETF stream.
RFC 4845 section 3 explains the document process:
3. IAB RFC Publication Process The following is a description of the process used by the IAB to publish IAB documents as RFCs. 1. The document is determined to be an IAB document by the IAB, as described in Section 1. 2. The IAB publishes an IAB draft (draft-iab-*). Comments on the draft are reviewed and may be integrated into successive iterations of the draft. In addition to considering comments received on the draft, the IAB may elect to refer the document to individuals or groups and explicitly solicit comments as appropriate. 3. For documents intended to be published as BCPs, the document is passed to the Internet Engineering Steering Group (IESG) with a sponsoring Area Director (AD), and follows the process outlined in [SPONSOR]. 4. For documents intended to be Informational RFCs, the remainder of this process is followed. 5. The chair of the IAB issues an IETF-wide Call for Comment on the IETF Announce mailing list. The comment period is normally no shorter than four weeks. 6. Comments received are considered for integration into the document. The IAB shall determine whether the document is ready for publication based on the comments received, or whether another round of document editing and, optionally, a further call for input is required. 7. The document is passed to the RFC Editor for publication as an IAB document Informational RFC.
The following sections elaborate on the current process in more detail, but the details are flexible. The point here is to document what our current working procedure is.
IAB Consensus Informational Documents
I-D for IAB consideration
When an IAB member considers a document for IAB consideration that document will be presented to the IAB as an Internet Draft. Normally these documents will be posted to the repository as individual submissions but in rare occassions the draft can be circulated on the IAB mailinglist (e.g. when a document is a result of an IAB action or a workshop report).
A draft does not necessarily need to be authored by an IAB member. Any member of the community can ask an IAB to bring a document to the IAB for adoption as an IAB document.
If a draft is brought to the IAB there the chair will reserve the next available techchat slot for discussion of the document (if that would cause undue delay a business slot will be used).
Approving an IAB document
During that slot the IAB will need to approve the adoption of the document as an IAB document. It is expected that all IAB members read the document so that they can engage in the discussion. The decision to purue publication as IAB Stream RFC will need to be made on rough consensus and the following questions act as a guide to the discussion:
- Does the document fit the IAB mission?
- What is the value add of the IAB saying this (for the IAB)?
- What is the timeframe by which this document needs to be published in order to be relevant?
- Is there a long term commitment from the IAB on pursuing the issue?
- What is the audience/target and what do we want to see people take away (what is the message)?
- Does the final document need full IAB review or specialist review (who are those specialists)
- Is this a statement or an offer for considerations?
The result of the discussion should be documented in such a way that it offers the background for future IABs om why an effort was finished.
In addition the document shepherd will provide and document a timeline for concluding the document.
The shepherd will work with the document to resolve issues. High-level issues that speak to the point that the IAB tries to make will need to be brought to the IAB.
The editor will use some sort of issue tracker (e.g. trac).
IAB last call
When the editor considers the document finished the IAB shepherd will bring the document to the IAB for a 2 weeks last call (or longer if multiple documents are to be reviewed at the same time, IAB members may ask for a little extra time).
Since we had a high barrier for entrance we should not end up in the situation that we have discussions about the topic being worthy for IAB publication. Obviously we may find out that the quality of the document is not satisfactory.
The document editor will work with the individuals who identified the issues to resolve those issues. Once that is done the document is ready for Call for Comments.
IETF Call for Comments
RFC 4845 section 3 states:
The chair of the IAB issues an IETF-wide Call for Comment on the IETF Announce mailing list. The comment period is normally no shorter than four weeks.
The Call for Comments is often done with a bias to close on a Sunday so that Monday start of business matters can be evaluated.
Any significant feedback, beyond nits, is brought to the IAB and are resolved as appropriate, preferably through e-mail.
After the feedback from the community has been incorporated the document is approved (pro-forma) by the IAB at its next meeting.
Appendix: IAB Members at the Time of Approval
The appendix lists a "IAB Members at the Time of Approval" section. This section is factual since it only speaks about the membership at a certain time. In rare cases the section might document that there was a rough consensus for publication but we strive to have all people mentioned. Disagreements with publication can appear in the public meeting minutes.
Issues brought up during this last call should be addressed.
The reasons for this section were articulated by Olaf Kolkman as "It takes a lot of in-depth knowledge to sort out who were on the IAB at the time the document was approved. I believe it is important that (in particular with non-workshop reports) the members at that time are willing to take responsibility and stand for the consensus achieved within the IAB." Leslie Daigle added: "part of the reason for listing the folks who were on the IAB when it was approved was to facilitate documents being edited across the annual membership boundary. I.e., you didn't have a flurry of publications in February, or a lull as the new IAB read through the all-but-finished IAB documents leftover from the previous team."
Reports on IAB-sponsored workshops do not reflect IAB consensus and follow a different model, even though they are still published in the IAB Stream. See published workshop reports for additional examples of language used in prior reports.
The following paragraph (based on text in RFC 4417 and RFC 4984) should be added at the end of the abstract:
Note that this document is a report on the proceedings of the workshop. The views and positions documented in this report are those of the workshop participants and do not necessarily reflect IAB views and positions.
Sample abstract 1:
This document reports the outcome of the <topic> Workshop that was held by the Internet Architecture Board (IAB) on <dates>, in <place>. The primary goal of the workshop was to <goal>. This report summarizes the discussions and conclusions of the workshop. <boilerplate trailer paragraph from above>
Sample abstract 2:
This document provides an overview of a workshop held by the Internet Architecture Board (IAB) on <topic>. The workshop was hosted by <host> in <place> on <dates>. The goal of the workshop was to <goal>. This report summarizes the discussions and lists the conclusions and recommendations to the Internet Engineering Task Force (IETF) community. <boilerplate trailer paragraph from above>
The following boilerplate (from RFC 1862) MAY be used in the introduction.
The Internet Architecture Board (IAB) holds occasional workshops designed to consider long-term issues and strategies for the Internet, and to suggest future directions for the Internet architecture. This long-term planning function of the IAB is complementary to the ongoing engineering efforts performed by working groups of the Internet Engineering Task Force (IETF), under the leadership of the Internet Engineering Steering Group (IESG) and area directorates.
Appendix: Workshop Participants
An appendix lists the workshop participants. Workshop reports do not contain an "IAB members at approval" section, since they are not IAB consensus documents.
The location of the workshops is not generally part of the doc title. For example:
* RFC 4417 Report of the 2004 IAB Messaging Workshop * RFC 4948 Report from the IAB workshop on Unwanted Traffic March 9-10, 2006 * RFC 6462 Report from the Internet Privacy Workshop
In the first-page header, each author's name would be listed without an organization.
A section titled "IAB Members at the Time of Approval" would be included.
The IAB would be listed in the Authors' Addresses section as follows:
Internet Architecture Board EMail: email@example.com
IAB Consensus BCPs
RFC 4845 section 1 states: "If the IAB has cause to publish a document as a Best Current Practice (BCP), it would fall under the approval process of the IETF standards stream of RFCs (see RFC 4844])."