Network Working Group A. Hagens
Internet-Draft S. Ginoza
Intended status: Informational R. Braden
Expires: November 21, 2008 RFC Editor
May 20, 2008
RFC Editor Proposal for Handling RFC Errata
draft-rfc-editor-errata-process-02
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 21, 2008.
Abstract
This document describes a web-based process for handling the
submission, verification, and posting of errata for the RFC Series.
The main concepts behind this process are (1) distributing the
responsibility for verification to the appropriate organization or
person for each RFC stream, and (2) using a Web portal to automate
the book-keeping for handling errata.
Hagens, et al. Expires November 21, 2008 [Page 1]
Internet-Draft RFC Errata Process May 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Background on RFC Errata . . . . . . . . . . . . . . . . . 3
2. Proposed Errata Process Using the Web Portal . . . . . . . . . 4
2.1. Reporting Errata . . . . . . . . . . . . . . . . . . . . . 5
2.2. Initial Notification Message . . . . . . . . . . . . . . . 6
2.3. Verifying Errata . . . . . . . . . . . . . . . . . . . . . 7
2.4. Posting Errata . . . . . . . . . . . . . . . . . . . . . . 7
2.5. Errata Announcements . . . . . . . . . . . . . . . . . . . 8
3. Role of the RFC Editor . . . . . . . . . . . . . . . . . . . . 8
4. Transition . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7. Informative References . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Possibilities for Posting Errata . . . . . . . . . . 11
Appendix B. Errata Processing before the Web Portal . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Intellectual Property and Copyright Statements . . . . . . . . . . 14
Hagens, et al. Expires November 21, 2008 [Page 2]
Internet-Draft RFC Errata Process May 2008
1. Introduction
This document describes a new set of the procedures and mechanisms
for handling RFC errata, to improve efficiency and accountability of
errata processing. The main concepts are (1) distributing
responsibility for errata verification to the appropriate body or
person for each RFC stream, and (2) using a Web portal to automate
the book-keeping task for verifying and posting errata.
The errata process assumes the organization of RFC publication into
four document streams [RFC4844]: (1) the IETF stream, which includes
both working group and individual submissions, (2) the IAB stream,
(3) the IRTF stream, and (4) the Independent Submission stream. We
propose that personnel representing each stream be responsible for
verifying the errata reported for that stream's RFCs. In particular,
we propose that one or more stream-specific parties (SSPs) be
designated with responsibility for verifying errata for each stream.
At the organizational level, the SSPs might be:
o IESG for IETF documents
o IAB for IAB documents
o IRSG for IRTF documents
o RFC Editor/Editorial Board for Independent Submissions
The IETF stream could be considered to be subdivided by area, so that
each Area Director could be an SSP for RFCs originating in that area.
The RFC publication process maintains the AD contact information for
each RFC, so errata reports for RFCs in the IETF document stream
could be sent to the appropriate ADs.
1.1. Background on RFC Errata
The RFC Editor began to collect and post RFC errata in 2000. The
idea was to discourage readers from repeatedly pointing out the same
typos in published RFCs. This evolved into the errata verification
and posting process described in Appendix B, which was a manually
operated, email-based task.
Unfortunately, our understanding of the errata problem was wrong in
several ways. The number of errors reported turned out to be
significantly greater than anticipated, and the process of vetting
and posting required more human resources.
Another issue with errata is that some of the reported errors are not
Hagens, et al. Expires November 21, 2008 [Page 3]
Internet-Draft RFC Errata Process May 2008
simply editorial, but rather correct technical contents of RFCs. A
savvy implementer of the specification can often, but not always,
figure out what was intended by the RFC as published, but technical
errors should be announced somehow. Furthermore, posting technical
errata for Standards Track documents should always involve the IESG,
as a matter of correct process. Technical errata may require much
review and discussion among the author(s), Area Directors, and other
interested parties. (See [HOW_TO_REPORT] for guidelines regarding
editorial vs. technical classification.)
We note that allowing technical errata is a slippery slope: there may
be a temptation to use errata to "fix" protocol design errors, rather
than publishing new RFCs that update the erroneous documents. In
general, an erratum is intended to report an error in a document,
rather than an error in the design of the protocol or other entity
defined in the document, but this distinction may be too imprecise to
avoid hard choices. For the IETF stream, these choices should be
made by the IESG, and are discussed in their proposed guidelines on
errata processing [IESG-Err-Proc].
In summary, errata have become a much larger, more complex, and more
important issue than they were originally. This proposal attempts to
address these problems.
2. Proposed Errata Process Using the Web Portal
To manage and automate the reporting, verifying, and posting of
errata, the RFC Editor has transitioned to a Web application
("portal"). This Web portal allows for a more uniform reporting
process, eases communication among the parties responsible for
verification, and automates the posting of errata as soon as they are
reported.
There are four possible states for an erratum under this proposal:
1. Reported - The erratum has been reported but is unverified.
2. Verified - The erratum has been edited as necessary and verified.
3. Rejected - The erratum was redundant or incorrect and has been
discarded.
4. Archived - The erratum is not a necessary update to the RFC.
However, it should be considered in future revisions of the RFC.
(Note that this state is not yet available; it is pending the
IESG's statement regarding errata processing [IESG-Err-Proc].)
Hagens, et al. Expires November 21, 2008 [Page 4]
Internet-Draft RFC Errata Process May 2008
Currently, Reported and Verified errata are posted (see Section 2.4
for more details).
For more information on the states and their definitions, and the
guidelines by which the IESG intends to classify errata into the the
above states, see [IESG-Err-Proc].
The Web interface supports the following functions:
1. Retrieve -- display all posted errata for a specific RFC number
or display a particular erratum by its errata ID number.
2. Report -- report a new erratum, as described below. (See
[HOW_TO_REPORT] for up-to-date instructions on reporting a new
erratum.)
3. Edit/Verify/Reject -- used by an SSP to edit the contents of an
erratum and change its state.
The following sections describe the proposed process in more detail.
2.1. Reporting Errata
A member of the Internet community (the "reporter") navigates to the
RFC errata page [ERRATA_PAGE] and enters the RFC number of the
document containing the error. All earlier errata for that RFC are
displayed, and the reporter is asked to check that the erratum does
not already appear in the full list of errata for any given RFC.
This should help prevent multiple reports of the same error.
The user then reports the erratum using a Web form to create a report
record in the RFC errata database. The report is composed of
information provided by the reporter, and is supplemented by data
drawn from the primary RFC Editor database. The erratum report
record includes the following fields:
This information is requested from the reporter:
RFC #
Type [editorial, technical]
Reporter name
Reporter email address
(Note that the address is provided for communication
purposes with the relevant SSPs and authors, but it is
not displayed in the online errata report.)
Section #
Original text
Corrected text
Hagens, et al. Expires November 21, 2008 [Page 5]
Internet-Draft RFC Errata Process May 2008
Notes
The above information is supplemented by information pulled from the
database:
Errata ID number
RFC title and associated draft string (if available)
Publication Date
Author(s)
Category ("status") of RFC
Source (Working Group Name, IAB, IRTF, or INDEPENDENT)
Area (for IETF stream)
Stream (IETF, IAB, IRTF, or INDEPENDENT)
Verifying Party (SSP Identity)
URL to the distinct erratum report
Generally, we want the reporter to enter a new erratum using the
Original and Corrected Text fields, as this allows for easier
verification. The free-text Notes field can be used for providing
rationale or for describing those errata that cannot easily be put
into the Original/Corrected format.
The Report page allows a set number of reports (i.e., 4) for the same
RFC to be submitted at the same time, using the Original/Corrected
form. By having the user separate the errata entries, the SSP should
have an easier time verifying each entry. We also hope that this
encourages users to submit only the most valuable errata.
The reporter is asked to make a judgment on the errata type --
technical vs. editorial. If the reporter has both editorial and
technical errors in the same RFC, the two classes of errata must be
entered as separate reports. This initial classification is useful
to the SSP; for example, it might allow technical errata to be
processed with higher priority than editorial errata, and it allows
the RFC Editor to monitor editorial errata to note frequent editorial
errors that could possibly lead to improvements in the editorial
process.
We expect that the reporter will usually make the right technical/
editorial classification, with the aid of published guidelines (see
[HOW_TO_REPORT]). However, in case of misclassification by the
reporter, the SSP can fix it when logged in as a verifier.
2.2. Initial Notification Message
Submitting the report triggers an email notification message to the
appropriate SSP, the RFC author(s), and the RFC Editor. Including
them all as addressees in one message facilitates cooperation in
Hagens, et al. Expires November 21, 2008 [Page 6]
Internet-Draft RFC Errata Process May 2008
verifying the error.
The message includes the information listed in Section 2.1. The SSP
could forward the notification email further; for example, an Area
Director might forward it to the chair of the responsible working
group, if it still exists.
In the case of early RFCs for which the RFC Editor does not have
associated stream or area information, the reports will be sent to
the IESG (as a whole) and the authors.
Author email addresses are often out of date. In these cases, the
relevant SSPs have the option of seeking current author contact
information or relying on other individuals with knowledge of the
subject matter to help determine the validity of the errata.
2.3. Verifying Errata
The initial notification message starts the verification process.
The SSP and the authors are expected to determine the validity of the
reported erratum, by whatever procedure the SSP or the stream owner
determines. The RFC Editor does not intend to (normally) track the
verification process. The SSP, not the author(s) or the RFC Editor,
has final responsibility for verifying or rejecting each report.
This helps to avoid a great deal of complexity and confusion.
Each SSP has a login account on the errata portal to edit errata
records as necessary. The SSP identity is added to the record and
the individual is able to edit, verify, or reject each erratum.
The Notes field allows users to submit information in any fashion
they like, so there is a possibility of multiple errors being
reported in this field. The SSP is able to edit the record and split
it into multiple records to maintain one record per erratum, as
necessary.
Based on experience, we know that some errata reports will require
significant email discussion between the reporter and the author(s)
and/or SSPs (in particular, the IESG) before the final decision on a
record can be made. The final outcome will be captured in the errata
entry, and any controversy or explanatory material can be recorded in
the Notes field.
2.4. Posting Errata
As soon as an erratum is submitted, it is available online, i.e., it
is posted as described below. The erratum entry is marked Reported
until its state is updated by verifiers as described above.
Hagens, et al. Expires November 21, 2008 [Page 7]
Internet-Draft RFC Errata Process May 2008
In this document, posting an erratum means that it is:
1. Available from the RFC errata page:
http://www.rfc-editor.org/errata.php.
2. Linked to from the results of the RFC search engine:
http://www.rfc-editor.org/rfcsearch.html.
3. Linked to from some HTML versions of the RFC. For example, see
http://tools.ietf.org/html/rfc2119.
The state of errata determines whether they are posted. Currently,
Reported and Verified errata are posted, and Rejected errata are not
posted. However, this can be altered to improve the errata display
for readers and implementers. For example, Rejected and Archived
errata could be hidden behind a link (as has been suggested).
The order in which errata are displayed for a single RFC (e.g.,
Verified Technical, Reported Technical, Verified Editorial, Reported
Editorial) also can be altered to improve the usability.
It sometimes happens that there are errata for errata, i.e., earlier
postings must be altered. In this case, the RFC Editor can do the
update as requested by an SSP or can grant an SSP temporary write
access to the record to be updated.
There are other possibilities for errata posting that should be
considered by the community; see Appendix A.
2.5. Errata Announcements
The RFC Editor proposes to announce verified technical errata
postings to the rfc-distribution list. If the SSP felt the errata
was important enough, they might want to submit a note to the ietf-
announce list. However, we do not believe it is necessary to
inundate the ietf-announce list with mail each time an errata is
verified, rejected, or edited.
3. Role of the RFC Editor
The role of the RFC Editor in errata processing is to:
1. Operate the Web portal.
2. Maintain the errata database.
Hagens, et al. Expires November 21, 2008 [Page 8]
Internet-Draft RFC Errata Process May 2008
3. Make changes in previously posted errata at the request of the
corresponding SSP, or give the SSP temporary write access to the
record.
4. Act as SSP for Independent Submissions.
5. Send periodic nudge messages to SSPs for errata that are in the
Reported state.
6. Track SSP and community requests for various features that will
make the job of reporting and verifying errata more efficient.
4. Transition
Errata from the original errata page have been made available from
the new Web portal. Generally, they are marked Verified without
listing the name of the verifier, as this information was not
associated with the errata records until November 2007.
Errata that were posted in the pending file (as described in
Appendix B) have been made available from the Web portal and are
marked as Reported or Verified, as appropriate. Lists of unverified
reports have been sent to the appropriate SSPs for review and
verification.
5. Security Considerations
It is necessary to have access control for errata reports. A
logged-in SSP is able to edit, verify, or reject any errata report on
an RFC that is the product of their stream. However, we propose that
once the SSP has submitted an erratum's final state (Verified or
Rejected) and the record entry has been committed to the errata
database, the SSP will lose write access to it. This is a safety
feature to prevent inadvertent or malicious changes to the database,
even if the passwords for some SSP logins may become fairly widely
known. However, the RFC Editor will always have write access to
posted entries and can make later changes if necessary.
The RFC Editor has chosen to use HTTPS as a reasonably secure login
mechanism. Also, the RFC Editor has obtained a signed certificate
from a CA for the errata verification pages, so that SSPs have
confidence that they are logging into the RFC Editor site.
Hagens, et al. Expires November 21, 2008 [Page 9]
Internet-Draft RFC Errata Process May 2008
6. IANA Considerations
There are no IANA considerations for this document.
7. Informative References
[ERRATA_PAGE] RFC Editor, "RFC Errata", February 2008,
<http://www.rfc-editor.org/errata.php>.
[HOW_TO_REPORT] RFC Editor, "How to Report Errata", February 2008,
<http://www.rfc-editor.org/how_to_report.html>.
[IESG-Err-Proc] "Proposed IESG Statement Regarding RFC Errata for
IETF Stream RFCs", Work in Progress, April 2008.
[RFC4844] Daigle, L. and Internet Architecture Board, "The RFC
Series and RFC Editor", RFC 4844, July 2007.
Hagens, et al. Expires November 21, 2008 [Page 10]
Internet-Draft RFC Errata Process May 2008
Appendix A. Possibilities for Posting Errata
Choosing any of these possibilities for posting errata should be
decided by the IETF community and its governing bodies.
1. Brian Carpenter has suggested an approach similar to that used by
W3C: Add a URL to every published RFC that points to its errata
(if any).
For W3C examples, see:
http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/ and
http://www.w3.org/TR/2006/REC-xml-names-20060816
They include the text:
"Please refer to the <errata> for this document, which may
include some normative corrections."
where <errata> is a hyperlink to the list of all errata or a
page that says:
"There are no errata to this document yet."
Similarly, a URL could be added to all (future) RFCs pointing to
where the relevant errata are posted.
2. Another possibility would be to add new errata files to the RFC
repository, e.g., with names of the form: rfcnnnn.err.txt. Such
a file would contain all the errata for the corresponding RFC.
3. As mentioned in Section 2.4, there are HTML versions of RFCs with
errata links; these are currently hosted by tools.ietf.org, but
they could be made available on the RFC Editor Web site as well.
Hagens, et al. Expires November 21, 2008 [Page 11]
Internet-Draft RFC Errata Process May 2008
Appendix B. Errata Processing before the Web Portal
The following is a summary of the RFC Editor errata verification and
posting process prior to the deployment of the Web portal in November
2007. The RFC Editor used to:
o Review email and relevant RFCs to ensure that the reported errata
actually appeared in the RFCs as available from
http://www.rfc-editor.org/. This does not mean that the errata
were reviewed and deemed correct, only that the reported erronous
text appears in the RFC (i.e., without judgment about the reports
correctness).
o Disentangle multiple errors reported in one message.
o Check that each error has not already been posted.
o Attempt to determine whether the errata are editorial or
technical.
o Forward each erratum report to the author(s) of the published RFC.
o Track bounce messages (contact information for authors is often
out of date) and try to find current contact information.
o Forward the message to the relevant ADs if we were unable to find
current author contact information.
o Track follow-up email.
o Figure out how to post when reporters/authors do not submit errata
in the original/new format. This is often a problem when
reporters submit email claiming an error, but do not offer
corrective text.
o Post verified errata and discard rejected errata.
There were three possible states for processing an erratum:
1. Reported - the erratum has been reported but is unverified.
2. Verified - the erratum has been edited as necessary and verified.
3. Rejected - the erratum was redundant or incorrect and has been
discarded.
Generally speaking, an erratum was posted when it was verified.
(Note that "posted" here means available online from the original RFC
Hagens, et al. Expires November 21, 2008 [Page 12]
Internet-Draft RFC Errata Process May 2008
errata page; the list of posting locations in Section 2.4 includes
those developed after 2000.) The exceptions were the "pending
errata", whose processing was delayed as described below.
During 2006, the RFC Editor was understaffed for the growing load of
RFCs to be published (see
http://www.rfc-editor.org/num_rfc_year.html). To catch up, the RFC
Editor suspended all activities not directly related to RFC
publication. As a result, more than a year's worth of errata reports
had not been verified or posted. As resources allowed, the RFC
Editor provided the following interim measures:
1. Made available, from the RFC Editor Web site, a mailbox text file
(mbox format) of all errata-related email (ftp://
ftp.rfc-editor.org/in-notes/pending-errata/pending-errata.msgs).
2. For those few errata that did get added to the errata database,
marked them UNVERIFIED.
Authors' Addresses
Alice Hagens
RFC Editor
4676 Admiralty Way
Marina del Rey, CA 90292
USA
Email: rfc-editor@rfc-editor.org
Sandy Ginoza
RFC Editor
4676 Admiralty Way
Marina del Rey, CA 90292
USA
Email: rfc-editor@rfc-editor.org
Robert Braden
RFC Editor
4676 Admiralty Way
Marina del Rey, CA 90292
USA
Email: rfc-editor@rfc-editor.org
Hagens, et al. Expires November 21, 2008 [Page 13]
Internet-Draft RFC Errata Process May 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
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.
Hagens, et al. Expires November 21, 2008 [Page 14]