Internet DRAFT - draft-rpc-errata-process
draft-rpc-errata-process
RSWG A. Russo
Internet-Draft J. Mahoney
Intended status: Informational RFC Production Center
Expires: 30 August 2024 27 February 2024
Current Process for Handling RFC Errata Reports
draft-rpc-errata-process-01
Abstract
This document describes the current 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 processing of erratum reports. This system was launched in
November 2007.
This draft documents the existing system as a means to facilitate
discussion to revamp how errata are reported, reviewed, and
publicized.
Discussion Venues
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/ajeanmahoney/errata-report-process.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on 30 August 2024.
Russo & Mahoney Expires 30 August 2024 [Page 1]
Internet-Draft Handling Errata Reports February 2024
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Background on RFC Errata . . . . . . . . . . . . . . . . 3
2. Current Errata Process Using the Web Portal . . . . . . . . . 4
2.1. Reporting Errata . . . . . . . . . . . . . . . . . . . . 5
2.2. Initial Notification Message . . . . . . . . . . . . . . 7
2.2.1. Technical Erratum Reports . . . . . . . . . . . . . . 7
2.2.2. Editorial Erratum Reports . . . . . . . . . . . . . . 8
2.3. Posting Erratum Reports . . . . . . . . . . . . . . . . . 9
2.4. Verifying Erratum Reports . . . . . . . . . . . . . . . . 10
2.5. Erratum Report Announcements . . . . . . . . . . . . . . 11
2.5.1. Technical Erratum Reports . . . . . . . . . . . . . . 11
2.5.2. Editorial Erratum Reports . . . . . . . . . . . . . . 12
3. Role of the RPC . . . . . . . . . . . . . . . . . . . . . . . 13
4. Security Considerations . . . . . . . . . . . . . . . . . . . 13
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
6. Informative References . . . . . . . . . . . . . . . . . . . 14
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
This document describes the procedures and mechanisms for handling
RFC erratum reports. The main concepts are (1) distributing
responsibility for report verification to the appropriate body or
person for each RFC stream, and (2) using a Web portal to automate
the tasks for verifying and posting erratum reports.
This process assumes the organization of RFC publication into five
document streams [RFC8729]: (1) the IETF Stream, which includes both
working group and individual submissions plus all RFCs that were
published before the concept of streams existed (known as legacy
RFCs), (2) the IAB Stream, (3) the IRTF Stream, (4) the Independent
Russo & Mahoney Expires 30 August 2024 [Page 2]
Internet-Draft Handling Errata Reports February 2024
Submission Stream, and (5) the Editorial Stream. Personnel
representing each stream, called the stream-specific party (SSP), are
responsible for verifying the erratum reports for that stream's RFCs.
At the organizational level, the SSPs are:
* IESG for legacy RFCs
* IESG for IETF Stream documents
* IAB for IAB Stream documents
* IRSG for IRTF Stream documents
* Independent Submissions Editor for Independent Submission Stream
documents
* RFC Series Approval Board for Editorial Stream documents
In addition, the RFC Production Center reviews editorial errata
reports from all streams and marks them as verified when possible, as
per [IESG-Err-Proc].
1.1. Background on RFC Errata
The RFC Production Center (RPC) 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 an errata
verification and posting process that was a manually operated, email-
based task. Errata from this period have been made available in the
current system and marked as Reported or Verified, as appropriate.
Generally, the name of the verifier is not given as this information
was not associated with errata records until the new system was put
in place.
Because the number of errors reported turned out to be significantly
greater than anticipated, and the process of vetting and posting
required more human resources, a web-based process
[ERRATA_SYS_PROPOSAL] was created and launched in November 2007.
Another reason for the current, web-based approach to handling
erratum reports is that about half the reports are not simply
editorial, but rather apply to the technical contents of RFCs. A
savvy implementer of the specification can often, but not always,
determine what was intended by the RFC as published, but technical
errors should be announced somehow. Furthermore, the posting of
technical errata for Standards Track documents should always involve
the IESG, as a matter of correct process. Technical errata may
Russo & Mahoney Expires 30 August 2024 [Page 3]
Internet-Draft Handling Errata Reports February 2024
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 to publish 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 are made by
the IESG and are discussed in their guidelines on errata processing
[IESG-Err-Proc].
2. Current Errata Process Using the Web Portal
To manage and automate the reporting, verifying, and posting of
errata, the rfc-editor.org website provides 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 erratum reports as soon as
they are reported.
There are four possible states for an erratum report:
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. Held for Document Update - The erratum is not a necessary update
to the RFC. However, it should be considered in future revisions
of the RFC.
Currently, reports in all states are posted (see Section 2.3 for more
details).
For more information on the states and their definitions, and the
guidelines by which the IESG classifies erratum reports into 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.
Russo & Mahoney Expires 30 August 2024 [Page 4]
Internet-Draft Handling Errata Reports February 2024
2. Report -- report a new erratum, as described below. (See
[HOW_TO_REPORT] for instructions on reporting a new erratum.)
3. Edit/Verify/Reject -- used by an SSP to edit the contents of an
erratum and change its status.
The following sections describe the process in more detail.
2.1. Reporting Errata
A member of the Internet community (the "reporter") navigates to the
RFC errata page [ERRATA_PAGE], enters the RFC number of the document
containing the error, and clicks the Search button. All earlier
erratum reports for that RFC are displayed. This includes reports of
any status (Verified, Reported, Held for Document Update, and
Rejected). The reporter is asked to check that the erratum does not
already appear on the errata page for any given RFC. This step is to
prevent multiple reports of the same error.
The reporter 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.org database. The erratum report
record includes the following fields:
The following information is requested from the reporter. All fields
must be filled in:
* 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 erratum report.)
* Publication format: Text, PDF, HTML (This field is present for
only RFC 8650 and higher.)
* Type: editorial, technical
* Section #
* Original text
* Corrected text
* Notes
Russo & Mahoney Expires 30 August 2024 [Page 5]
Internet-Draft Handling Errata Reports February 2024
The reporter is asked to make a judgment on the erratum 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 RPC to verify editorial erratum reports and to note frequent
editorial errors that could possibly lead to improvements in the
editorial process.
With the aid of published guidelines (see [HOW_TO_REPORT]), the
reporter should make the right technical/editorial classification.
However, if the reporter does misclassify the report, the SSP can fix
the classification when logged in as a verifier.
The reporter should enter a new erratum using the Original and
Corrected Text fields, as this allows for easier verification. The
reporter can use the free-text Notes field to provide the rationale
or to describe those errata that cannot easily be put into the
Original/Corrected format.
When the reporter submits the report, they are shown a preview of it.
They can choose to edit the report, cancel, or submit. They must
successfully navigate a reCAPTCHA in order to complete the report
submission.
The information provided by the reporter 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, INDEPENDENT, or Editorial)
* Area (for IETF Stream)
* Stream (IETF, IAB, IRTF, INDEPENDENT, or Editorial)
* Verifying Party (SSP Identity)
* URL to the distinct erratum report
Russo & Mahoney Expires 30 August 2024 [Page 6]
Internet-Draft Handling Errata Reports February 2024
When a report is successfully submitted, a notification is sent via
email (see Section 2.2), and the report is posted to the rfc-
editor.org website (see Section 2.3).
2.2. Initial Notification Message
Submitting the report triggers an email notification message to
multiple parties; see the notification lists below. Including
multiple parties facilitates cooperation in verifying the error and
transparency in the process.
Notifications are determined by stream and type of erratum report and
are sent by rfc-editor@rfc-editor.org to the following SSPs.
Note that while SSP email addresses are maintained by the database,
author email addresses, especially for older RFCs, are often out of
date. In these cases, the SSP has 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
erratum report.
2.2.1. Technical Erratum Reports
Technical erratum reports are sent to SSPs, and the reporter and rfc-
editor@rfc-editor.org are CCed.
Legacy RFCs:
* To: IESG
* CC: reporter, rfc-editor@rfc-editor.org
IETF Stream:
* To: authors, ADs of the area from which the document came,
document shepherd
* CC: reporter, working group, rfc-editor@rfc-editor.org
IAB Stream:
* To: authors, IAB
* CC: reporter, rfc-editor@rfc-editor.org
IRTF Stream:
* To: authors, IRSG
Russo & Mahoney Expires 30 August 2024 [Page 7]
Internet-Draft Handling Errata Reports February 2024
* CC: reporter, rfc-editor@rfc-editor.org, research group
Independent Submission Stream:
* To: authors, ISE
* CC: reporter, rfc-editor@rfc-editor.org
Editorial Stream:
* To: authors, RSAB
* CC: reporter, rfc-editor@rfc-editor.org, RSWG
2.2.2. Editorial Erratum Reports
All editorial erratum reports are sent to rfc-editor@rfc-editor.org,
and other SSPs are CCed:
Legacy RFCs:
* To: rfc-editor@rfc-editor.org
* CC: reporter
IETF Stream:
* To: rfc-editor@rfc-editor.org
* CC: reporter, authors, working group
IAB Stream:
* To: rfc-editor@rfc-editor.org
* CC: reporter, authors, IAB
IRTF Stream:
* To: rfc-editor@rfc-editor.org
* CC: reporter, authors, research group
Independent Submission Stream:
* To: rfc-editor@rfc-editor.org
* CC: reporter, authors
Russo & Mahoney Expires 30 August 2024 [Page 8]
Internet-Draft Handling Errata Reports February 2024
Editorial Stream:
* To: rfc-editor@rfc-editor.org
* CC: reporter, authors, RSWG
The message includes the information listed in Section 2.1.
2.3. Posting Erratum Reports
As soon as an erratum is submitted, it is available online as
described below. The erratum entry is marked Reported until its
state is updated by verifiers as described in Section 2.4. Duplicate
and junk reports are available and marked as Reported only until they
are deleted from the database by the RPC.
In this document, posting an erratum means that:
* The report can be discovered through the RFC errata search page:
https://www.rfc-editor.org/errata.php (https://www.rfc-editor.org/
errata.php).
* A link to the RFC's errata page appears on the following:
- the results of the RFC search engine: https://www.rfc-
editor.org/rfcsearch.html (https://www.rfc-editor.org/
rfcsearch.html).
- the RFC's info page. For example, see https://www.rfc-
editor.org/info/rfc2119 (https://www.rfc-editor.org/info/
rfc2119).
- On the HTML format of the RFC. For example, https://www.rfc-
editor.org/rfc/rfc2119.html (https://www.rfc-editor.org/rfc/
rfc2119.html).
All erratum reports for a single RFC, except for obvious spam
reports, are posted in the following order:
* Verified Technical
* Verified Editorial
* Held for Document Update Technical
* Held for Document Update Editorial
* Rejected Technical
Russo & Mahoney Expires 30 August 2024 [Page 9]
Internet-Draft Handling Errata Reports February 2024
* Rejected Editorial
* Reported Technical
* Reported Editorial
All erratum reports are also available at https://www.rfc-editor.org/
errata.json (https://www.rfc-editor.org/errata.json).
2.4. Verifying Erratum Reports
The initial notification message starts the verification process.
The RPC determines the validity of editorial erratum reports and also
handles any junk or duplicate reports, whether they are labeled as
editorial or technical.
Junk erratum reports contain bogus content in the Original text,
Corrected text, and/or Notes fields. The RPC deletes such a report
from the database and sends an email message to all recipients of the
report notification, except for the reporter, notifying them that the
report has been deleted.
If an erratum report duplicates an existing report, the RPC deletes
the report and sends a reply-all to the notification message to say
the report has been deleted.
The SSP and the authors are expected to determine the validity of any
technical erratum report, by whatever procedure the SSP or the stream
owner determines.
The RPC does not track the verification process for technical erratum
reports. The SSP, not the author(s) or the RPC, has final
responsibility for verifying or rejecting each technical erratum
report. This helps to avoid a great deal of complexity and
confusion.
Each SSP has a login account on the errata portal to edit and verify
erratum reports. The SSP identity is added to the record and the
individual is able to edit, verify, hold, or reject each erratum.
The Notes field allows reporters 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 split the report into
multiple records to maintain one record per erratum report, as
necessary.
Russo & Mahoney Expires 30 August 2024 [Page 10]
Internet-Draft Handling Errata Reports February 2024
Some erratum reports require significant email discussion between the
reporter and the author(s) and/or SSPs (in particular, the IESG)
before the final decision on a report can be made. The final outcome
is captured in the erratum entry, and any controversy or explanatory
material is recorded in the Notes field.
It sometimes happens that there are errata for errata, i.e., earlier
postings must be altered. In this case, the RFC Editor can update
the report as requested by an SSP or can grant an SSP temporary write
access to the record to be updated.
Once verified, the erratum is available for viewing in the RFC's HTML
format "inline" (for example, see https://www.rfc-editor.org/rfc/
inline-errata/rfc3261.html (https://www.rfc-editor.org/rfc/inline-
errata/rfc3261.html)) in addition to being on the RFC's errata page
and discoverable through errata search functionality.
2.5. Erratum Report Announcements
Like the notification of submissions, the announcement of a verified
(or held or rejected) erratum report varies by stream:
Notifications are determined by stream and type of erratum report.
2.5.1. Technical Erratum Reports
The announcement of technical erratum reports are sent from rfc-
editor@rfc-editor.org to the following:
Legacy RFCs:
* To: reporter, authors
* CC: verifier, IESG, rfc-editor@rfc-editor.org
IETF Stream:
* To: reporter, authors
* CC: verifier, IESG, working group, IANA, rfc-editor@rfc-editor.org
IAB Stream:
* To: reporter, authors
* CC: verifier, IAB, IAB chair, rfc-editor@rfc-editor.org
IRTF Stream:
Russo & Mahoney Expires 30 August 2024 [Page 11]
Internet-Draft Handling Errata Reports February 2024
* To: reporter, authors
* CC: verifier, IRSG, research group, IANA, rfc-editor@rfc-
editor.org
Independent Submission Stream:
* To: reporter, authors
* CC: verifier, ISE, Document Shepherd, IANA, rfc-editor@rfc-
editor.org
Editorial Stream:
* To: reporter, authors
* CC: verifier, RSAB, RSWG, IANA, rfc-editor@rfc-editor.org
2.5.2. Editorial Erratum Reports
The announcement of verified editorial erratum reports are sent from
rfc-editor@rfc-editor.org to the following:
Legacy RFCs:
* To: reporter, author
* CC: verifier, rfc-ed@rfc-editor.org, IESG, IANA
IETF Stream:
* To: reporter, authors
* CC: verifier, rfc-ed@rfc-editor.org, IESG, working group, IANA
IAB Stream:
* To: reporter, authors
* CC: verifier, rfc-ed@rfc-editor.org, IAB, IAB chair
IRTF Stream:
* To: reporter, authors
* CC: verifier, rfc-ed@rfc-editor.org, IRSG, research group, IANA
Independent Submission Stream:
Russo & Mahoney Expires 30 August 2024 [Page 12]
Internet-Draft Handling Errata Reports February 2024
* To: reporter, authors
* CC: verifier, rfc-ed@rfc-editor.org, ISE, IANA
Editorial Stream:
* To: reporter, authors
* CC: verifier, RSAB, RSWG, IANA, rfc-ed@rfc-editor.org
3. Role of the RPC
The role of the RPC in errata processing is to:
1. Operate the Web portal.
2. Maintain the errata database.
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 verifier for editorial erratum reports.
5. Remove junk and duplicate reports.
6. Track SSP and community requests for various features that will
make the job of reporting and verifying errata more efficient.
4. Security Considerations
It is necessary to have access control in order to process erratum
reports. A logged-in SSP is able to edit, verify, or reject any
erratum report on an RFC that is the product of their stream. Once
the SSP has submitted an erratum's final state (Verified, Held, or
Rejected) and the record entry has been committed to the erratum
database, the SSP loses write access to it. This is to prevent
inadvertent or malicious changes to the database, even if the
passwords for some SSP logins may become fairly widely known.
However, the RPC continues to have write access to posted entries and
can make later changes if necessary.
The portal uses HTTPS as a reasonably secure login mechanism. Also,
the rfc-editor.org website has a signed certificate from a CA, so
that SSPs have confidence that they are logging into the rfc-
editor.org website.
Russo & Mahoney Expires 30 August 2024 [Page 13]
Internet-Draft Handling Errata Reports February 2024
5. IANA Considerations
This document has no IANA actions.
6. Informative References
[ERRATA_PAGE]
RFC Editor, "RFC Errata",
<https://www.rfc-editor.org/errata.php>.
[ERRATA_SYS_PROPOSAL]
RFC Editor, "RFC Editor Proposal for Handling RFC Errata",
20 May 2008, <https://datatracker.ietf.org/doc/draft-rfc-
editor-errata-process/>.
[HOW_TO_REPORT]
RFC Editor, "How to Report Errata",
<https://www.rfc-editor.org/how_to_report.html>.
[IESG-Err-Proc]
IESG, "IESG Processing of RFC Errata for the IETF Stream",
7 May 2021,
<https://www.ietf.org/about/groups/iesg/statements/
processing-errata-ietf-stream/>.
[RFC8729] Housley, R., Ed. and L. Daigle, Ed., "The RFC Series and
RFC Editor", RFC 8729, DOI 10.17487/RFC8729, February
2020, <https://www.rfc-editor.org/rfc/rfc8729>.
Acknowledgements
This document is based on [ERRATA_SYS_PROPOSAL], written by Alice
Russo (née Hagens), Sandy Ginoza, and Bob Braden. This document
received helpful feedback from Sandy Ginoza, TBD...
Authors' Addresses
Alice Russo
RFC Production Center
Email: arusso@amsl.com
Jean Mahoney
RFC Production Center
Email: jmahoney@amsl.com
Russo & Mahoney Expires 30 August 2024 [Page 14]