Checklist for Internet-Drafts (IDs) submitted for RFC publication
Abstract
This memo defines a list of often called "ID-NITS" that
need to be checked before an Internet-Draft will be accepted
for IESG consideration.
The intent is that WG chairs check an I-D for any nits before
submitting a request-for-publication, so that is before AD-review.
[Source: http://www.ietf.org/Draft-ID-Checklist.html, 2008-07-08]
Table of Contents
1.
Introduction
2.
Form nits
2.1.
Formatting
2.2.
Required sections - all I-Ds
2.3.
Sometimes-required sections
3.
Content issues
4.
Protocol Issues
5.
Change Log
6.
Normative References
§
Author's Address
1.
Introduction
All Internet Drafts which are offered for publication as RFCs
must conform to the following requirements or they will be
returned to the author(s)/editor(s) for revision.
The WG Chairs are responsible
for having this list checked before submission to the ADs.
A handy tool (awk script) to check most of the formatting nits
(as in Sections 2.1 and 2.2 below) is available at
http://ietf.levkowetz.com/tools/idnits/,
courtesy of Henrik Levkowetz.
Another set of handy tools is available at
the IETF TOOLS
pages.
Checking for content related issues (as in Sections
2.3, 3, and 4 below) needs a human eye.
The content issues have to be checked early in the development
of documents, being technically integral.
The WG Chairs are responsible for this too.
The ADs will not accept the document and so will not put it on
the IESG agenda if this check has not been done.
Responsibility for all checking is with the authors in the case
of an individual submission.
Notes:
This document only talks about "finished" Internet-Drafts.
That is those I-Ds for which the IESG gets a request for
publication. However, it is strongly RECOMMENDED to follow
these rules/guidelines for documents that go to WG Last Call
as well.
Guidelines for all Internet-Drafts are in
Guidelines to Authors of Internet-Drafts,
and are not repeated here.
As a suggestion for productivity improvement, it is strongly
RECOMMENDED to use XML2RFC [RFC2629] (Rose, M., “Writing I-Ds and RFCs using XML,” June 1999.)
as source files for generating an Internet-Draft.
(There is even an online
xml2rfc
tool to generate the nroff and Internet-Draft .txt files).
That tool automatically takes care of most of
the formatting, administrative and bureaucratic rules.
There is a rumor that the tool will soon also take care of
all the content issues ;-)
2.
Form nits
2.1.
Formatting
In principle, the RFC-Editor can take care of a few small formatting
errors. And if there are only a few, then they will do so.
However, if many errors exist, the document will be returned to the
author(s)/editor(s)/WG for fixes.
In any event, please realize that not following the formatting rules
will most probably delay publication and does consume time that can
be spend on other work.
See "Instructions to RFC Authors"
[I‑D.rfc‑editor‑rfc2223bis] (Reynolds, J. and R. Braden, “Instructions to Request for Comments (RFC) Authors,” July 2004.) section 3
for details and further rules. Here is a checklist of formatting
problems rules that often get neglected:
- No text beyond the 72nd column of a line.
This is especially important for diagrams and code, which the RFC
Editor may not be able to trivially reformat to fall within the
margins.
- Must be ragged right
- No hyphenation for line-breaks
- No footnotes
- ASCII-only, no control characters (other than CR, NL and FF).
- Do not number the "Status of Memo" or "Abstract"
sections
- Do not add a numbered reference in the I-D boilerplate to RFC 3978
or RFC 3979 (or to RFC 2026, RFC 3667 or RFC 3668 for
older documents).
If you do, it makes it harder for the RFC editor to process
the document when they strip off the I-D boilerplate.
- Reasonably well formatted for readibility and clarity
- Use network byte order in diagrams
(see [I‑D.rfc‑editor‑rfc2223bis] (Reynolds, J. and R. Braden, “Instructions to Request for Comments (RFC) Authors,” July 2004.) section 3.4)
2.2.
Required sections - all I-Ds
The following are REQUIRED sections in all Internet-Drafts:
- Internet Draft boilerplate
It MUST not contain boilerplate that prohibits publication
as an RFC, see [RFC3978] (Bradner, S., “IETF Rights in Contributions,” March 2005.), Section 5.2.
- List of authors/editors
There should not be more than 5 authors/editors (see
http://www.rfc-editor.org/policy.html)
- Abstract
- Table of Contents, required if document is more than 15 pages
- Introduction
- Security Considerations
- IANA Considerations
- A.
- Must specify if IANA has to create a new registry or modify
rules for an existing registry.
- B.
- Must specify if the document requires IANA to assign or update
values in an IANA registry before RFC publication.
- C.
- See "Guidelines for Writing an IANA Considerations Section in RFCs"
[RFC2434] (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” October 1998.) and in some cases also "IANA Allocation
Guidelines For Values In the Internet Protocol and Related Headers"
[RFC2780] (Bradner, S. and V. Paxson, “IANA Allocation Guidelines For Values In the Internet Protocol and Related Headers,” March 2000.). In some case "Assigning Experimental and
Testing Numbers Considered Useful" [RFC3692] (Narten, T., “Assigning Experimental and Testing Numbers Considered Useful,” January 2004.)
may help as well.
- D.
- If there is no action for IANA, the section should say that,
e.g., including something like "This document has no actions
for IANA."
- References MUST be split into normative and informative sections
(see http://www.rfc-editor.org/policy.html).
- Author's Address
- IPR Disclosure, verbatim from [RFC3978] (Bradner, S., “IETF Rights in Contributions,” March 2005.) section 5.1.
- IPR Notice, verbatim from [RFC3979] (Bradner, S., “Intellectual Property Rights in IETF Technology,” March 2005.) section 5.
If these notices are not present, then the RFC-Editor will add them
(as per RFC 3979 section 5), but it will speed up the process if
the notices are already present in the Internet-Draft.
- Copyright Notice and Disclaimer, verbatim from
[RFC3978] (Bradner, S., “IETF Rights in Contributions,” March 2005.) sections 5.4 and 5.5,
updated as per
[RFC4748] (Bradner, S., “RFC 3978 Update to Recognize the IETF Trust,” October 2006.) sections 2.6 and 2.7.
2.3.
Sometimes-required sections
- URLs and e-mail addresses @ietf.org
If your Internet-Draft specifies that a new URL, e-mail list,
or e-mail alias be created @ietf.org, then you MUST explain why
it is needed.
Creation of a new URL, e-mail list, or e-mail alias @ietf.org
requires the approval of an IETF Area Director.
When you request publication of your I-D as an RFC, the shepherding
AD will review your explanation as part of the evaluation process.
If the AD concurs that a new URL, e-mail list, or e-mail alias is
needed, and if your document is approved for publication as an RFC,
then the Secretariat will create the URL, e-mail list, or e-mail
alias before the RFC is published.
3.
Content issues
- Abstract
- A.
- Should be meaningful to someone not versed in the technology;
most abbreviations must be expanded on first use.
- B.
- no citations
- C.
- See [I‑D.rfc‑editor‑rfc2223bis] (Reynolds, J. and R. Braden, “Instructions to Request for Comments (RFC) Authors,” July 2004.) section 4.5.
- D.
- if your document obsoletes or updates a previous RFC, then:
- say so in the abstract.
- Explain in the introduction how and why this document
updates or obsoletes an earlier document.
- Add the "Updates:" and "Obsoletes:" lines on the frontpage.
Here is an example of what the frontpage should look like:
Network Working Group <yourname>
Internet-Draft <your affiliation>
Obsoletes: xxxx (if approved) August 29, 2006
Updates: yyyy, zzzz (if approved)
Intended status: Best Current Practice
Expires: February 21, 2007
...
Abstract
This document describes .....
It obsoletes RFC xxxx and updates RFC yyyy and RFC zzzz.
- Security Considerations section
MUST have meaningful exploration of security issues raised by the
proposal, SHOULD include both risks and description of solutions
or workarounds.
See "Guidelines for Writing RFC Text on Security Considerations"
[RFC3552] (Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” July 2003.)
and "Guidelines for Mandating the Use of IPsec"
[I‑D.bellovin‑useipsec] (Bellovin, S., “Guidelines for Mandating the Use of IPsec Version 2,” October 2007.)
It is also important to use the proper terminology for security
terms, as defined in [RFC4949] (Shirey, R., “Internet Security Glossary, Version 2,” August 2007.).
- If capitalized MUST/SHOULD etc is used, then the terms must be
defined (or [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) must be normatively referenced).
Also read RFC 2119 to see what it says about using MUST etc.
- Specific IPR (e.g., patent claims & terms) must not be in an RFC
(or Internet-Draft).
Any claims must go to the IETF IPR web page and notice that there is
some IPR claim.
The mandatory IPR Notice from [RFC3979] (Bradner, S., “Intellectual Property Rights in IETF Technology,” March 2005.) section 5 points
readers to the IETF IPR web page.
- Use of formal languages should be in conformance with the IESG
statement on the use of formal languages - See
http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in-specs.txt
In particular:
- A.
- All MIB modules SHOULD have correct SYNTAX, so they should
compile cleanly using:
smilint -m -s -l 6 -i namelength-32
An online WEB service is available for syntax checking at:
http://www.ibr.cs.tu-bs.de/projects/libsmi/tools/.
It allows you to extract the MIB module from a document for
your own local use, but you can also directly run a syntax check.
You can also download the libsmi tools for local use.
In most cases there should be no errors or warnings
present in the report. Please evaluate all diagnostic
messages before assuming that they are OK. If in
doubt, feel free to check on the
ietfmibs@ops.ietf.org
mailing list or with the OPS ADs.
- B.
- Besides the SYNTAX checking, a MIB document should also be
checked against the "Guidelines for MIB Authors and Reviewers"
[RFC4181] (Heard, C., “Guidelines for Authors and Reviewers of MIB Documents,” September 2005.)
- C.
- All ABNF must be checked. A tool is available from
www.apps.ietf.org
See [RFC4234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.) for information about IETF ABNF.
If ABNF is used, you MUST include a normative reference to
RFC 4234.
- D.
- Protocol specifications that use XML should always use
well-formed XML at a minimum. Sample XML instances
included in a specification have to be well-formed,
and if the XML is supposed to be valid (according to
the current W3C definition of validity), the samples
must reference and be validated using an appropriate
XML Schema, DTD, or other standard validation mechanism
that is structurally and syntactically correct.
Links to tools to check XML validity, including a schema
checker and a validating parser, can be found at
www.apps.ietf.org
Other guidelines for the use of XML in IETF protocols can
be found in BCP 70 [RFC3470] (Hollenbeck, S., Rose, M., and L. Masinter, “Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols,” January 2003.).
- E.
- XML provides structures, such as the <any> element
information item in XML Schema, to allow element
extensions. If these structures are included in a
protocol, the protocol specification must include clear
guidance on how, when, and where the extension structures,
such as versioning, can be used.
- F.
- XML Schemas, Namespaces, and Resource Description Framework
(RDF) Schemas should be registered with the IANA using the
procedures described in BCP 81 [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).
- Addresses used in examples SHOULD use fully qualified
domain names instead of literal IP addresses, and SHOULD use
example fqdn's such as foo.example.com instead of real-world fqdn's.
See [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” June 1999.) for example domain names that can be
used.
There is also a range of IP addresses set aside for this purpose:
- A.
- For IPv4 these are 192.0.2.0/24 (see [RFC3330] (IANA, “Special-Use IPv4 Addresses,” September 2002.)).
- B.
- For IPv6 these are 2001:DB8::/32 (see [RFC3849] (Huston, G., Lord, A., and P. Smith, “IPv6 Address Prefix Reserved for Documentation,” July 2004.)).
Private addresses that would be used in the real world SHOULD be
avoided in examples.
Similarly, real telephone numbers should not be used.
Instead use those numbers that were reserved for examples or fictitious use.
Available numbersfor use in examples are:
- C.
- UK: +44-<geographic-area-code>-496-<0000-0999>
(see http://www.ofcom.org.uk/telecoms/ioi/numbers/num_drama)
- D.
- USA: +1-<area code>-555-<0100-0199>
(see http://www.nanpa.com/nas/public/form555MasterReport.do?method=display555MasterReport)
- References
- A.
- All references must be stable and resolvable.
- B.
- A bare HTTP URL is not generally considered a stable reference.
For Web-only documents, adding a reference number, title and/or
an author will help make the reference more stable.
- C.
- Judgment can be used here; the stability of normative references
is even more important than the stability of informative references.
- D.
- In case of references to Internet-Drafts, use the format:
author, "title" (I-D file name).
Normative references to I-Ds will cause a standards-track or BCP
document to wait in the RFC-Editor queue (see
RFC-Editor queue)
for the referenced I-Ds to be published as RFCs.
- E.
- Normative and informative references to non-IETF documents are
permitted. However, it is best to minimize such normative
references, because assessing their status when the IETF
document advances on the standards-track is very difficult.
It is important to use the exact title, author name(s),
organization and publication date.
- Avoid text that will become outdated after RFC is published.
Examples include non-permanent URLs, mentions of specific mailing
lists as places to send comments on a document,
or referring to specific WGs as a place to perform specific future
actions (e.g., reviewing followup documents). In some cases (like
the ORGANIZATION clause in MIB modules), references to working groups
are impossible to avoid; however, generally, Internet-Drafts should
not assign powers or responsibilities to WGs unless the WG in
question will exist as long as the practice documented in the
published RFC remains valid. In cases where a specific WG is
expected to be a focal point for future action, it is acceptable
to give the task to the IESG, giving instructions on how the
action is expected to be delegated, e.g., by forwarding to an
appropriate WG or other set of experts.
4.
Protocol Issues
- Avoid IPv4 specificity. Both IPv4 and IPv6 must be supportable,
unless the protocol is naturally IPv4 specific or IPv6 specific.
- No application can be permitted to cause catastrophic congestion.
See [RFC2914] (Floyd, S., “Congestion Control Principles,” September 2000.) for details - applications using TCP
or SCTP will normally fulfill this requirement automatically.
- If any sort of end-to-end checksum or integrity check is being
used (especially, but not limited to, cryptographic checksums or
MACs), specify precisely the contents of the fields to be checksummed,
and exactly what order the operations are done in.
Pay special attention to any area reserved for the checksum itself.
- All user-visible text fields must be internationalizable.
See [RFC2277] (Alvestrand, H., “IETF Policy on Character Sets and Languages,” January 1998.).
For most cases, this means UTF-8 [RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.).
If text fields are included in some calculation, like matching,
sorting etc, it must be described in detail how those operations
are applied to the Unicode/ISO 10646 character set. See
"stringprep" [RFC3454] (Hoffman, P. and M. Blanchet, “Preparation of Internationalized Strings ("stringprep"),” December 2002.) for more
information on the recommended way of handling comparisons.
5.
Change Log
- jul 4th, 2008, Revision 1.8, published
as www.ietf.org/ID-Checklist.html
- Updated text in section 3, item 6, to clarify the text.
That is, the "SHOULD prefereably" and "prefarbly" have
both been changed into "SHOULD".
- Replaced reference to RFC2828 into reference to RFC4949
which obsoletes 2828. This is a reference to
Internet Security Glossary, Version 2.
- Oct 26th, 2006, Revision 1.7, published
as www.ietf.org/ID-Checklist.html
- Updated text on Copyright Notice and Disclaimer, to indicate
it has been updated by
[RFC4748] (Bradner, S., “RFC 3978 Update to Recognize the IETF Trust,” October 2006.) sections 2.6 and 2.7.
- Aug 28st, 2006, Revision 1.6, published
as www.ietf.org/ID-Checklist.html
- Changed MIB SYNTAX checking instructions to use the new
SMIlint WEB interface instead of the older mail interface.
- Added more text about wording for stating that a document
updates or obsoletes an existing RFC.
- Changed citation/reference for ABNF from RFC2234 to RFC4234.
- Mar 30th, 2006, Revision 1.5, published
as www.ietf.org/ID-Checklist.html
- Added text to explain that reserved example phone numbers
should be used in examples instead of real phone numbers.
Added pointers to web pages for example numbers in UK and USA.
- Added text that one needs to state in abstract if a doc updates
or obsoletes an existing RFC.
- Sep 24th, 2005, Revision 1.4, published
as www.ietf.org/ID-Checklist.html
- Reference RFC 4181 (BCP 111) instead of internet-draft
for MIB review guidelines.
- Added a ptr to the IETF TOOLS pages
- Jun 6th, 2005, Revision 1.3, published
as www.ietf.org/ID-Checklist.html
- Reference RFCs 3978 and 3979 instead of 3667 and 3668.
- Feb 3rd, 2005, Revision 1.2, published
as www.ietf.org/ID-Checklist.html
- Correction to point revision 4 of MIB review Guidelines.
- Correction to point RFC3849 for IPv6 addresses.
- Add ptr to RFC 2828 for proper use of security terms.
- Clarification of sect 2.2 bullet 1.
- Correction to point smilint instructions for MIB documents.
- May 18th, 2004, Revision 1.1, IESG approved and published
as www.ietf.org/ID-Checklist.html
- Correction to point to proper RFC 3667 for icopyright matters.
- May 17th, 2004, Revision 1.0, IESG approved and published
as www.ietf.org/ID-Checklist.html
- Minor edits based on final review.
- May 14th, 2004, Revision 0.6, IESG final review.
- Presentation as private document instead of Internet-Draft.
- Fix spelling errors and apply some other grammatical cleanups.
- moved topic on internationalization from the "Content issues"
the to "Protocol issues" section.
- May 13th, 2004, Revision 0.5
- Added titles of documents and RFC 3692 to IANA Considerations topic.
- May 12th, 2004, Revision 0.4
- Changed more text after IESG, IANA and RFC-Editor reviews.
- IANA Considerations section is now mandatory.
- Added text on not using transient mailing lists and such.
- May 10th, 2004, Revision 0.3
- Changed bulleted lists in numbered lists for easier referencing.
- Added blank lines for better readability.
- IANA considerations section now needed for MIB documents
(i.e. it is no longer exempted).
- April 2nd, 2004, Revision 0.2
- Converted source into XML2RFC [RFC2629] (Rose, M., “Writing I-Ds and RFCs using XML,” June 1999.) format.
- Added click-able references to authoritative documents.
- Added text for things that RFC-Editor may fix.
- Added text for examples of IPv6 addresses.
- Replaced RFC 2026 IPR and COPYRIGHT rules with
those from RFCs 3667, 3668 and 3669.
- Added some words on references to non-IETF documents.
- Added text on required XML checking.
- Added text on URLs and email addresses @ietf.org
- Added text to emphasize good grammar/English.
- February 4, 2003, Revision 0.1
- Added clarification on warnings from MIB.
- Changed text for IANA MIB registration prior to
RFC publication.
- Added a pointer to RFC3552 for security considerations.
6. Normative References
[I-D.bellovin-useipsec] |
Bellovin, S., “Guidelines for Mandating the Use of IPsec Version 2,” draft-bellovin-useipsec-07 (work in progress), October 2007 (TXT). |
[I-D.rfc-editor-rfc2223bis] |
Reynolds, J. and R. Braden, “Instructions to Request for Comments (RFC) Authors,” draft-rfc-editor-rfc2223bis-08 (work in progress), July 2004 (TXT). |
[RFC2119] |
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
[RFC2277] |
Alvestrand, H., “IETF Policy on Character Sets and Languages,” BCP 18, RFC 2277, January 1998 (TXT, XML). |
[RFC2434] |
Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” BCP 26, RFC 2434, October 1998 (TXT, XML). |
[RFC2606] |
Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” BCP 32, RFC 2606, June 1999 (TXT). |
[RFC2629] |
Rose, M., “Writing I-Ds and RFCs using XML,” RFC 2629, June 1999 (TXT, HTML, XML). |
[RFC2780] |
Bradner, S. and V. Paxson, “IANA Allocation Guidelines For Values In the Internet Protocol and Related Headers,” BCP 37, RFC 2780, March 2000 (TXT). |
[RFC2828] |
Shirey, R., “Internet Security Glossary,” RFC 2828, May 2000 (TXT). |
[RFC2914] |
Floyd, S., “Congestion Control Principles,” BCP 41, RFC 2914, September 2000 (TXT). |
[RFC3330] |
IANA, “Special-Use IPv4 Addresses,” RFC 3330, September 2002 (TXT). |
[RFC3454] |
Hoffman, P. and M. Blanchet, “Preparation of Internationalized Strings ("stringprep"),” RFC 3454, December 2002 (TXT). |
[RFC3470] |
Hollenbeck, S., Rose, M., and L. Masinter, “Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols,” BCP 70, RFC 3470, January 2003 (TXT, HTML, XML). |
[RFC3552] |
Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” BCP 72, RFC 3552, July 2003 (TXT). |
[RFC3629] |
Yergeau, F., “UTF-8, a transformation format of ISO 10646,” STD 63, RFC 3629, November 2003 (TXT). |
[RFC3669] |
Brim, S., “Guidelines for Working Groups on Intellectual Property Issues,” RFC 3669, February 2004 (TXT). |
[RFC3688] |
Mealling, M., “The IETF XML Registry,” BCP 81, RFC 3688, January 2004 (TXT). |
[RFC3692] |
Narten, T., “Assigning Experimental and Testing Numbers Considered Useful,” BCP 82, RFC 3692, January 2004 (TXT). |
[RFC3849] |
Huston, G., Lord, A., and P. Smith, “IPv6 Address Prefix Reserved for Documentation,” RFC 3849, July 2004 (TXT). |
[RFC3978] |
Bradner, S., “IETF Rights in Contributions,” BCP 78, RFC 3978, March 2005 (TXT). |
[RFC3979] |
Bradner, S., “Intellectual Property Rights in IETF Technology,” BCP 79, RFC 3979, March 2005 (TXT). |
[RFC4181] |
Heard, C., “Guidelines for Authors and Reviewers of MIB Documents,” BCP 111, RFC 4181, September 2005 (TXT). |
[RFC4234] |
Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” RFC 4234, October 2005 (TXT, HTML, XML). |
[RFC4748] |
Bradner, S., “RFC 3978 Update to Recognize the IETF Trust,” BCP 78, RFC 4748, October 2006 (TXT). |
[RFC4949] |
Shirey, R., “Internet Security Glossary, Version 2,” RFC 4949, August 2007 (TXT). |
Author's Address
|
Bert Wijnen |
|
Independent Consultant |
|
Schagen 33 |
|
3461 GL Linschoten |
|
Netherlands |
Phone: |
+31-348-407-775 |
Email: |
bertietf@bwijnen.net |