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]
2. Form nits
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
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.
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 ;-)
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:
The following are REQUIRED sections in all Internet-Drafts:
- Must specify if IANA has to create a new registry or modify rules for an existing registry.
- Must specify if the document requires IANA to assign or update values in an IANA registry before RFC publication.
- 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.
- If there is no action for IANA, the section should say that, e.g., including something like "This document has no actions for IANA."
- Should be meaningful to someone not versed in the technology; most abbreviations must be expanded on first use.
- no citations
- See [I‑D.rfc‑editor‑rfc2223bis] (Reynolds, J. and R. Braden, “Instructions to Request for Comments (RFC) Authors,” July 2004.) section 4.5.
- 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.
- All MIB modules SHOULD have correct SYNTAX, so they should compile cleanly using:An online WEB service is available for syntax checking at:smilint -m -s -l 6 -i namelength-32
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 firstname.lastname@example.org mailing list or with the OPS ADs.
- 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.)
- 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.
- 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.).
- 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.
- 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.).
Private addresses that would be used in the real world SHOULD be avoided in examples.
- For IPv4 these are 192.0.2.0/24 (see [RFC3330] (IANA, “Special-Use IPv4 Addresses,” September 2002.)).
- For IPv6 these are 2001:DB8::/32 (see [RFC3849] (Huston, G., Lord, A., and P. Smith, “IPv6 Address Prefix Reserved for Documentation,” July 2004.)).
- UK: +44-<geographic-area-code>-496-<0000-0999> (see http://www.ofcom.org.uk/telecoms/ioi/numbers/num_drama)
- USA: +1-<area code>-555-<0100-0199> (see http://www.nanpa.com/nas/public/form555MasterReport.do?method=display555MasterReport)
- All references must be stable and resolvable.
- 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.
- Judgment can be used here; the stability of normative references is even more important than the stability of informative references.
- 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.
- 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.
|[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).|
|3461 GL Linschoten|