RFC 7322
RFC Style Guide
Part 1 of 4 💖 more is coming, so don't go anywhere bestie! 🫶
RFC 7322: RFC Style Guide ✨
Okay bestie, this is RFC 7322, the RFC Style Guide 📖 It was published in September 2014 as Informational, so it's not a standard, it's a permanent record of how the RFC Series does things 💅 It was written by H. Flanagan and S. Ginoza of the RFC Editor, and it's a product of the Internet Architecture Board (IAB) 🎀 It obsoletes RFC 2223 and its ISSN is 2070-1721 🌸
Abstract 🦋
So this doc describes the fundamental and unique style conventions and editorial policies that the RFC Series uses right now. It captures the RFC Editor's basic requirements and gives guidance on the style and structure of an RFC. Extra guidance lives on a website, which is experimental by nature and gets prepared for future inclusion in the RFC Style Guide 🌈 This document obsoletes RFC 2223, "Instructions to RFC Authors".
Status of This Memo 📜
This doc is not an Internet Standards Track specification. It's published for informational purposes 💜
It's a product of the Internet Architecture Board (IAB) and represents information the IAB decided was valuable to keep on permanent record. It represents the consensus of the Internet Architecture Board (IAB). Documents approved for publication by the IAB are not a candidate for any level of Internet Standard, see Section 2 of RFC 5741 ✨
Want the current status, any errata, or a way to send feedback? Check http://www.rfc-editor.org/info/rfc7322 🔥
Copyright Notice ©️
Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. 💖
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please review these carefully, bestie, because they describe your rights and restrictions with respect to this doc 🫶
Table of Contents 🗂️
1. Introduction ....................................................3
2. RFC Editor's Philosophy .........................................4
3. RFC Style Conventions ...........................................5
3.1. Language ...................................................5
3.2. Punctuation ................................................5
3.3. DNS Names and URIs .........................................6
3.4. Capitalization .............................................6
3.5. Citations ..................................................6
3.6. Abbreviation Rules .........................................7
4. Structure of an RFC .............................................8
4.1. First-Page Header ..........................................9
4.1.1. Author/Editor .......................................9
4.1.2. Organization ........................................9
4.1.3. "ISSN: 2070-1721" ..................................10
4.1.4. Updates and Obsoletes ..............................10
4.2. Full Title ................................................10
4.3. Abstract Section ..........................................11
4.4. RFC Editor or Stream Notes Section ........................11
4.5. Status of This Memo Section ...............................11
4.6. Copyright, Licenses, and IPR Boilerplate Section ..........11
4.7. Table of Contents Section .................................11
4.8. Body of the Memo .........................................12
4.8.1. Introduction Section ...............................12
4.8.2. Requirement Language Section .......................12
4.8.3. IANA Considerations Section ........................13
4.8.4. Internationalization Considerations Section ........13
4.8.5. Security Considerations Section ....................13
4.8.6. References Section .................................14
4.8.6.1. URIs in RFCs ..............................15
4.8.6.2. Referencing RFCs ..........................15
4.8.6.3. Referencing STDs and BCPs .................16
4.8.6.4. Referencing Internet-Drafts ...............17
4.8.6.5. Referencing Errata ........................18
4.8.6.6. Referencing Other Standards Development
Organizations (SDOs) ......................18
4.9. Appendices Section ........................................19
4.10. Acknowledgements Section .................................19
4.11. Contributors Section .....................................19
4.12. "Author's Address" or "Authors' Addresses" Section .......20
5. Security Considerations ........................................20
6. References .....................................................20
6.1. Normative References ......................................20
6.2. Informative References ....................................20
Appendix A. Related Procedures ....................................23
A.1. Dispute Resolution .........................................23
A.2. Returning an I-D to the Document Stream ....................23
A.3. Revising This Document and Associated Web Pages ............23
IAB Members at the Time of Approval ...............................24
Acknowledgements ..................................................24
Contributors ......................................................24
Authors' Addresses ................................................241. Introduction 🌸
The whole point of the RFC publication process is to produce docs that are readable, clear, consistent, and reasonably uniform 💅 The basic formatting conventions for RFCs were set up in the 1970s by the original RFC Editor, Jon Postel. This document describes the fundamental and unique style conventions and editorial policies currently used for the RFC Series [RFC4844]. It's meant to be a stable, rarely updated reference for authors, editors, and reviewers 📖
The RFC Editor also keeps a web portion of the Style Guide (see Appendix A.3) that covers issues as they come up and shows how the RFC Editor plans to handle them. When new style issues show up, the RFC Editor will first address them on the web portion of the Style Guide [STYLE-WEB]. Those topics may become part of the RFC Style Guide when it gets revised ✨
The world of technical publishing has generally accepted rules for grammar, punctuation, capitalization, sentence length and complexity, parallelism, etc. The RFC Editor generally follows these accepted rules as defined by the Chicago Manual of Style (CMOS) [CMOS], with a few important exceptions. Those exist to avoid ambiguity in complex technical prose, to handle mixtures of text and computer languages, or to preserve historical formatting rules. This document presents these exceptions as applied or recommended by the RFC Editor 🧚
All RFCs begin as Internet-Drafts (also called I-Ds), and a well-written, properly constructed Internet-Draft [ID-GUIDE] gives a strong basis for a good RFC 🎀 The RFC Editor accepts Internet-Drafts from specified streams for publication [RFC4844] and applies the rules and guidelines for the RFC Series during the editorial process 💖
2. RFC Editor's Philosophy 💅
Authors might find it helpful to understand the RFC Editor's goals during publication, which are to:
- Prepare the document according to RFC style and format.
- Make the document as clear, consistent, and readable as possible.
- Correct larger content/clarity issues, and flag any unclear passages for author review.
- Fix inconsistencies (e.g., terms that appear in various forms, text that appears multiple times, or inconsistent capitalization).
The RFC Editor strives for consistency within:
a. the document,
b. a cluster of documents [CLUSTER], and
c. the series of RFCs on the subject matter.
The editorial process of the RFC Editor is not an additional technical review of the document 🔍 When the RFC Editor suggests wording changes for clarity and readability, it's up to the author, working group, or stream-approving body to decide whether those changes affect the technical meaning of the document [RFC4844]. If the original wording more accurately represents the technical content being described, it takes precedence over editorial conventions 🫶
Editing sometimes creates tension between author and editor. The RFC Editor tries to minimize this conflict for RFC publication while constantly striving to produce a uniformly excellent document series. The RFC Editor calls this fundamental tension "editorial balance," and keeping that balance is an ongoing concern for them 🌈 There's a prime directive that must rule over grammatical conventions: do not change the intended meaning of the text 🚨
If the RFC Editor can't edit a document without seriously risking a change in meaning, the document may be returned to the stream-approving body for review. See Appendix A.2 for more information 💀
3. RFC Style Conventions 🦋
This Style Guide does not use terminology as defined in RFC 2119 [BCP14]. In this document, lowercase use of "must" and "should" indicates changes the RFC Editor will make automatically to conform with this Style Guide, versus those that may be questioned if not applied. The lowercase "must" indicates those changes that will be applied automatically and are not at the discretion of the authors. The lowercase "should" indicates the RFC Editor's recommended use, but conformance with the recommendations is not required, and the RFC Editor may question whether the guidance may be applied 🍓
3.1. Language 🌍
The RFC publication language is English. Spelling may be either American or British, as long as an individual document is internally consistent. Where both American and British English spelling are used within a document or cluster of documents, the text will be modified to be consistent with American English spelling 💜
3.2. Punctuation ✍️
- No overstriking (or underlining) is allowed.
- When a sentence ended by a period is immediately followed by another sentence, there must be two blank spaces after the period.
- A comma is used before the last item of a series, e.g.,
"TCP service is reliable, ordered, and full duplex"
- When quoting literal text, punctuation is placed outside quotation marks, e.g.,
Search for the string "Error Found".
When quoting general text, such as general text from another RFC, punctuation may be included within the quotation marks, e.g.,
RFC 4844 indicates that "RFCs are available free of charge to anyone via the Internet."
Quotation marks are not necessary when text is formatted as a block quotation 🎀
3.3. DNS Names and URIs 🌐
DNS names, whether or not in URIs, that are used as generic examples in RFCs should use the particular examples defined in "Reserved Top Level DNS Names" [BCP32], to avoid accidental conflicts 👑
Angle brackets are strongly recommended around URIs [STD66], e.g.,
3.4. Capitalization ✨
- Capitalization must be consistent within the document and ideally should be consistent with related RFCs. Refer to the online table of decisions on consistent usage of terms in RFCs [TERMS]. 💅
- Per CMOS guidelines, the major words in RFC titles and section titles should be capitalized (this is sometimes called "title case"). Typically, all words in a title will be capitalized, except for internal articles, prepositions, and conjunctions. 👑
- Section titles that are in sentence form will follow typical sentence capitalization. 🌸
- Titles of figures may be in sentence form or use title case. 🎀
3.5. Citations 🦋
- References and citations must match. That is, there must be a reference for each citation used, and vice versa. 🫶
- Citations must be enclosed in square brackets (e.g., "[CITE1]"). 💖
- A citation/reference tag must not contain spaces.
Example: "[RFC2119]" rather than "[RFC 2119]"
However, the proper textual naming of an RFC contains a space.
Example: "See RFC 2119 [BCP14] for more information."
- Cross-references within the body of the memo and to other RFCs must use section numbers rather than page numbers, as pagination may change per format and device. 📖
3.6. Abbreviation Rules 🧚
Abbreviations should be expanded in document titles and upon first use in the document. The full expansion of the text should be followed by the abbreviation itself in parentheses. The exception is an abbreviation that is so common that the readership of RFCs can be expected to recognize it immediately; examples include (but are not limited to) TCP, IP, SNMP, and HTTP. The online list of abbreviations [ABBR] provides guidance. Some cases are marginal, and the RFC Editor will make the final judgment, weighing obscurity against complexity. 🤔
Note: The online list of abbreviations is not exhaustive or definitive. It is a list of abbreviations appearing in RFCs and sometimes reflects discussions with authors, Working Group Chairs, and/or Area Directors (ADs). Note that some abbreviations have multiple expansions. Additionally, this list includes some terms that look like abbreviations but that are actually fixed names for things and hence cannot and should not be expanded. These are noted as "No Expansion".
4. Structure of an RFC 🌈
A published RFC will largely contain the elements in the following list. Some of these sections are required, as noted. Those sections marked with "*" will be supplied by the RFC Editor during the editorial process when necessary. Sections are allowed to contain nothing but subsections. The rules for each of these elements are described in more detail below. 📋
First-page header * [Required]
Title [Required]
Abstract [Required]
RFC Editor or Stream Note * [Upon request]
Status of This Memo * [Required]
Copyright Notice * [Required]
Table of Contents * [Required]
Body of the Memo [Required]
1. Introduction [Required]
2. Requirements Language (RFC 2119)
3. ...
MAIN BODY OF THE TEXT
6. ...
7. IANA Considerations [Required in I-D]
8. Internationalization Considerations
9. Security Considerations [Required]
10. References
10.1. Normative References
10.2. Informative References
Appendix A.
Appendix B.
Acknowledgements
Contributors
Author's Address [Required]Within the body of the memo, the order shown above is strongly recommended. Exceptions may be questioned. Outside the body of the memo, the order above is required. The section numbers above are for illustrative purposes; they are not intended to correspond to required numbering in an RFC. 🔥
The elements preceding the body of the memo should not be numbered. Typically, the body of the memo will have numbered sections and the appendices will be labeled with letters. Any sections that appear after the appendices should not be numbered or labeled (e.g., see "Contributors" above). 🦋
4.1. First-Page Header 💌
Headers will follow the format described in "RFC Streams, Headers, and Boilerplates" [RFC5741] and its successors. In addition, the following conventions will apply. 🎀
4.1.1. Author/Editor ✍️
The determination of who should be listed as an author or editor on an RFC is made by the stream.
The author's name (initial followed by family name) appears on the first line of the heading. Some variation, such as additional initials or capitalization of family name, is acceptable. Once the author has selected how their name should appear, they should use that display consistently in all of their documents. 💖
The total number of authors or editors on the first page is generally limited to five individuals and their affiliations. If there is a request for more than five authors, the stream-approving body needs to consider if one or two editors should have primary responsibility for this document, with the other individuals listed in the Contributors or Acknowledgements section. There must be a direct correlation of authors and editors in the document header and the Authors' Addresses section. These are the individuals that must sign off on the document during the AUTH48 process and respond to inquiries, such as errata. 🫶
4.1.2. Organization 🏢
The author's organization is indicated on the line following the author's name.
For multiple authors, each author name appears on its own line, followed by that author's organization. When more than one author is affiliated with the same organization, the organization can be "factored out," appearing only once following the corresponding Author lines. However, such factoring is inappropriate when it would force an unacceptable reordering of author names. 🌸
If an author cannot or will not provide an affiliation for any reason, "Independent", "Individual Contributor", "Retired", or some other term that appropriately describes the author's affiliation may be used. Alternatively, a blank line may be included in the document header when no affiliation is provided. 🌈
4.1.3. "ISSN: 2070-1721" 🔢
The RFC Series has been assigned an International Standard Serial Number of 2070-1721 [ISO3297]. It will be included by the RFC Editor. ✨
4.1.4. Updates and Obsoletes 🔄
When an RFC obsoletes or updates a previously published RFC or RFCs, this information is included in the document header. For example:
"Updates: nnnn"or"Updates: nnnn, ..., nnnn""Obsoletes: nnnn"or"Obsoletes: nnnn, ... , nnnn"
If the document updates or obsoletes more than one document, numbers will be listed in ascending order. 🧾
4.2. Full Title 👑
The title must be centered below the rest of the heading, preceded by two blank lines and followed by one blank line.
Choosing a good title for an RFC can be a challenge. A good title should fairly represent the scope and purpose of the document without being either too general or too specific and lengthy. 🤞
Abbreviations in a title must generally be expanded when first encountered (see Section 3.6 for additional guidance on abbreviations). 🧠
It is often helpful to follow the expansion with the parenthesized abbreviation, as in the following example:
Encoding Rules for the
Common Routing Encapsulation Extension Protocol (CREEP)The RFC Editor recommends that documents describing a particular company's private protocol should bear a title of the form "Foo's ... Protocol" (where Foo is a company name), to clearly differentiate it from a protocol of more general applicability. 🏷️
4.3. Abstract Section 💜
Every RFC must have an Abstract that provides a concise and comprehensive overview of the purpose and contents of the entire document, to give a technically knowledgeable reader a general overview of the function of the document. 🌟
Composing a useful Abstract generally requires thought and care. Usually, an Abstract should begin with a phrase like "This memo ..." or "This document ..." A satisfactory Abstract can often be constructed in part from material within the Introduction section, but an effective Abstract may be shorter, less detailed, and perhaps broader in scope than the Introduction. Simply copying and pasting the first few paragraphs of the Introduction is allowed, but it may result in an Abstract that is both incomplete and redundant. Note also that an Abstract is not a substitute for an Introduction; the RFC should be self-contained as if there were no Abstract. 🙈
Similarly, the Abstract should be complete in itself. It will appear in isolation in publication announcements and in the online index of RFCs. Therefore, the Abstract must not contain citations. 🚫
4.4. RFC Editor or Stream Notes Section 📝
A stream-approving body may approve the inclusion of an editorial note to explain anything unusual about the process that led to the document's publication or to note a correction. In this case, a stream note section will contain such a note. 🍓
Additionally, an RFC Editor Note section may contain a note inserted by the RFC Editor to highlight special circumstances surrounding an RFC. 🦄
4.5. Status of This Memo Section 📜
The RFC Editor will supply an appropriate "Status of This Memo" as defined in RFC 5741 [RFC5741] and "Format for RFCs in the IAB Stream" [IAB-FORM]. 🌷
4.6. Copyright, Licenses, and IPR Boilerplate Section ⚖️
The full copyright and license notices are available on the IETF Trust Legal Provisions documents website [IETF-TRUST]. 🔗
4.7. Table of Contents Section 🗂️
A Table of Contents (TOC) is required in all RFCs. It must be positioned after the Copyright Notice and before the Introduction. 💅
4.8. Body of the Memo 🎀
Following the TOC is the body of the memo. 🫧
Each RFC must include an Introduction section that (among other things) explains the motivation for the RFC and (if appropriate) describes the applicability of the document, e.g., whether it specifies a protocol, provides a discussion of some problem, is simply of interest to the Internet community, or provides a status report on some activity. The body of the memo and the Abstract must be self-contained and separable. This may result in some duplication of text between the Abstract and the Introduction; this is acceptable. ✨
4.8.1. Introduction Section 🌟
The Introduction section should always be the first section following the TOC (except in the case of MIB module documents). While "Introduction" is recommended, authors may choose alternate titles such as "Overview" or "Background". These alternates are acceptable. 🦋
For MIB module documents, common practice has been for "The Internet-Standard Management Framework" [MIB-BOILER] text to appear as Section 1. 🧚
4.8.2. Requirements Language Section ✨
okay so some docs use certain CAPITALIZED words ("MUST", "SHOULD", etc.) to say exactly how strict a technical feature is 💅 RFC 2119 [BCP14] gives those words a default meaning in IETF docs. If you use that meaning, RFC 2119 must be cited (the way RFC 2119 says to) and listed as a normative reference. Otherwise, the doc has to spell out what the words mean instead 🤓
This section must show up as part of the body of the memo (as this doc defines it). It must be part of, or come after, the Introduction section 🌸
These words count as part of the technical content of the doc. They're there to guide implementers on specific features, usually for interoperability reasons. RFC 2119 says:
Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmisssions) For example, they must not be used to try to impose a particular method on implementers where the method is not required for interoperability.
ngl that's a whole vibe check 🫶 use the caps words sparingly, bestie, and don't use them to boss people around about methods that don't matter for interoperability 💅
4.8.3. IANA Considerations Section ✨
for guidance on how to register IANA-related values or create new registries that IANA will manage, check out "Guidelines for Writing an IANA Considerations Section in RFCs" [BCP26] 🦋
the RFC Editor will update the text once the IANA assignments are made 🌈 it's super helpful for authors to clearly mark where text needs updating for the newly assigned values. For example, using "TBD1", "TBD2", etc. is recommended in the IANA Considerations section and in the body of the memo 🎀
if the authors gave values for IANA to assign, the RFC Editor will check that those values match what's actually registered on the IANA site. When writing a given value, consistent use of decimal or hexadecimal is recommended 🔥
if any IANA-related info isn't clear, the RFC Editor will work with IANA to send questions to the authors, so assignments and values get inserted properly 🧚
the RFC Editor will remove an IANA Considerations section that says there are no IANA considerations (although such a section is required in the Internet-Draft preceding the RFC) 💀
4.8.4. Internationalization Considerations Section ✨
all RFCs that deal with internationalization issues should have a section describing those issues 🌍 see "IETF Policy on Character Sets and Languages" [BCP18], Section 6, for more information 🍓
4.8.5. Security Considerations Section ✨
all RFCs must contain a section that discusses the security considerations relevant to the specification 🔐 see "Guidelines for Writing RFC Text on Security Considerations" [BCP72] for more information.
security is NOT a side quest, bestie 😭 this section is where the doc tells you what could go wrong, so it has to be complete.
note that additional boilerplate material for RFCs containing MIB and YANG modules also exists 🧠 see "Security Guidelines for IETF MIB Modules" [MIB-SEC] and "yang module security considerations" [YANG-SEC] for details 💜
4.8.6. References Section ✨
the reference list is solely for recording reference entries. Introductory text is not allowed 🙈
the RFC style lets you use any of a variety of reference styles, as long as you use them consistently within a document. Where necessary, some reference styles have been described for use within the Series, so check out the examples in this document 📚
the RFC Editor makes sure that references to other RFCs point to the most current RFC available on that topic (unless there's a reason not to do so) ✨ when referring to an obsoleted document, it's common practice to also refer to the most recent version 🌸
a reference to an RFC that has been assigned an STD [RFC1311], BCP [RFC1818], or FYI [FYI90] sub-series number must include the sub-series number of the document. Note that the FYI series was ended by RFC 6360. RFCs that were published with an FYI sub-series number and still maintain the FYI number must include the sub-series number in the reference 🎀
reference lists must indicate whether each reference is normative or informative. Normative references are essential to implementing or understanding the content of the RFC, and informative references provide additional information 🤓 more info about this is in the IESG's statement "Normative and Informative References" [REFS]. When both normative and informative references exist, the references section should be split into two subsections:
s. References
s.1. Normative References
xxx
...
xxx
s.2. Informative References
xxx
...
xxxreferences will generally appear in alphanumeric order by citation tag 🔤 where there are only normative or informative references, no subsection is required. The top-level section should say "Normative References" or "Informative References" 💅
normative references to Internet-Drafts will cause publication of the RFC to be suspended until the referenced draft is also ready for publication. Then the RFC Editor will update the entry to refer to the RFC and publish both documents simultaneously 🦋
4.8.6.1. URIs in RFCs ✨
the use of URIs in references is acceptable, as long as the URI is the most stable (i.e., unlikely to change and expected to be continuously available) and a direct reference is possible 🔗 the URI will be verified as valid during the RFC editorial process 🫶
if a dated URI (one that includes a timestamp for the page) is available for a referenced web page, its use is required 🕰️
note that URIs may not be the sole information provided for a reference entry 🌈
4.8.6.2. Referencing RFCs ✨
the following format is required for referencing RFCs. Note the ordering for multiple authors: the format of the name of the last author listed is different from that of all the previous authors in the list 👑
for one author or editor:
[RFCXXXX] Last name, First initial., Ed. (if applicable),
"RFC Title", Sub-series number (if applicable),
RFC number, Date of publication,
<http://www.rfc-editor.org/info/rfc#>.Example:
[RFC3080] Rose, M., "The Blocks Extensible Exchange
Protocol Core", RFC 3080, March 2001,
<http://www.rfc-editor.org/info/rfc3080>.for two authors or editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if applicable),
"RFC Title", Sub-series number (if applicable),
RFC number, Date of publication,
<http://www.rfc-editor.org/info/rfc#>.Example:
[RFC6323] Renker, G. and G. Fairhurst, "Sender RTT
Estimate Option for the Datagram Congestion
Control Protocol (DCCP)", RFC 6323, July 2011,
<http://www.rfc-editor.org/info/rfc6323>.for three or more authors or editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable),
Last name, First initial., Ed. (if applicable),
and First initial. Last name, Ed. (if applicable),
"RFC Title", Sub-series number (if applicable),
RFC number, Date of publication,
<http://www.rfc-editor.org/info/rfc#>.Example:
[RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah,
"TCP Sender Clarification for Persist
Condition", RFC 6429, December 2011,
<http://www.rfc-editor.org/info/rfc6429>.4.8.6.3. Referencing STDs and BCPs ✨
Internet Standards (STDs) and Best Current Practices (BCPs) may consist of a single RFC or multiple RFCs 📦 when an STD or BCP that contains multiple RFCs is referenced, the reference entry should include ALL of the RFCs comprising that sub-series. The authors should refer to specific RFC numbers as part of the text (not as citations) and cite the sub-series number 🧁 including the URI to the STD or BCP info page (see Section 3.2.3 of [RFC5741]) is recommended 🔗 the text should appear as follows:
See RFC 1034 [STD13].for an STD or BCP that contains one RFC:
[STDXXX] Last name, First initial., Ed. (if applicable),
"RFC Title", Sub-series number, RFC number, Date of
publication, <http://www.rfc-editor.org/info/std#>.Example:
[STD72] Gellens, R. and J. Klensin, "Message Submission
for Mail", STD 72, RFC 6409, November 2011,
<http://www.rfc-editor.org/info/std72>.for an STD or BCP that contains two or more RFCs:
[STDXXX] Last name, First initial., Ed. (if applicable),
"RFC Title", Sub-series number, RFC number, Date of
publication.
Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if applicable),
"RFC Title", Sub-series number, RFC number, Date of
publication.
<http://www.rfc-editor.org/info/std#>Example:
[STD13] Mockapetris, P., "Domain names - concepts and
facilities", STD 13, RFC 1034, November 1987.
Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
<http://www.rfc-editor.org/info/std13>4.8.6.4. Referencing Internet-Drafts ✨
references to Internet-Drafts may only appear as informative references 🌷 given that several revisions of an I-D may be produced in a short time frame, references must include the posting date (month and year), the full Internet-Draft file name (including the version number), and the phrase "Work in Progress" 🚧 authors may reference multiple versions of an I-D. If the referenced I-D was also later published as an RFC, then that RFC must also be listed 💖
[SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if
applicable), "I-D Title", Work in Progress,
draft-string-NN, Month Year.Example:
[RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide",
Work in Progress, draft-flanagan-style-01,
June 2013.4.8.6.5. Referencing Errata ✨
the following format is required when a reference to an erratum report is necessary 🐞
[ErrNumber] RFC Errata, Erratum ID number, RFC number.
[Err1912] RFC Errata, Erratum ID 1912, RFC 2978.4.8.6.6. Referencing Other Standards Development Organizations (SDOs) ✨
okay so when you're citing a doc from another SDO that lists its authors, the suggested format looks like this 💅
[SYMBOLIC-TAG]
Last name, First initial. and First initial. Last name,
"Document Title", Document reference number, Date of
publication, <URI if available>.
[W3C.REC-xml11]
Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
Yergeau, F., and J. Cowan, "Extensible Markup Language
(XML) 1.1 (Second Edition)", W3C Recommendation
REC-xml11-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml11-20060816>.the author order has to match the order on the actual document, and you use the common abbreviated name of the SDO 🫶
if there's no author list, the format changes a little bit 🌸
[SYMBOLIC-TAG] Organization, "Document Title", Document
reference number, Date of publication,
<URI if available>.and here's an example 🧚
[IEEE802.1Q] IEEE, "Local and Metropolitan Area
Networks -- Media Access Control (MAC)
Bridges and Virtual Bridged Local Area
Networks", IEEE Std 802.1Q-2011, August 2011,
<http://standards.ieee.org/findstds/standard/
802.1Q-2011.html>.4.9. Appendices Section
the RFC Editor likes references to go before the Appendices, lowkey a neat little rule 🎀 appendices get labeled like "Appendix A. Title", "A.1. Title", "Appendix B. Title", and so on ✨
4.10. Acknowledgements Section
this one is optional 🌈 you can use it instead of a Contributors section, or alongside one. authors use it to publicly thank people who gave feedback on a doc, and to note any docs that text was borrowed from 💖
4.11. Contributors Section
also optional! this section shouts out people who made big contributions to the doc 🙌
the RFC Editor doesn't decide who counts as a contributor, same as with the Author's Address section. that call belongs to the stream 👑
the Contributors section can include short notes about what each person did ("Sam contributed Section 3" is giving main character energy 💅), plus their affiliations. the author(s) can also decide to include contact addresses for contributors who'd be useful future contacts for questions about the RFC 🦋 if you do, the format should look similar to the Author's Address section 🍓
4.12. "Author's Address" or "Authors' Addresses" Section
this section is required, and it gives contact info for the author(s) listed in the first-page header 🎀
contact info has to include a long-lived email address. you can also add a postal address and/or phone number if you want. if you do include a postal address, it should have the country name, using the English short name from the ISO 3166 Maintenance Agency [ISO_OBP] 🌍 the whole point is (1) to make it crystal clear which author is which (like, the John Smith who works for FooBar Systems, iykyk 🙈) and (2) to give future readers a way to reach out with questions or comments 💜
⚠️ munged email addresses (where you deliberately scramble an address so bots and crawlers can't read it, to dodge spam) are NOT it in an archival document series. readers need to be able to actually contact the author, so address munging is not allowed in RFCs. no cap, it's a hard no 💀
5. Security Considerations
this document has no security considerations 🔒✨ (bestie, that's a whole vibe, and a clean one!)
6. References
6.1. Normative References
[STYLE-WEB]
RFC Editor, "Web Portion of the Style Guide",
<http://www.rfc-editor.org/rfc-style-guide/part2.html>.6.2. Informative References
[ABBR] RFC Editor Abbreviations List,
<http://www.rfc-editor.org/rfc-style-guide/
abbrev.expansion.txt>.
[BCP14] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997,
<http://www.rfc-editor.org/info/bcp14>.
[BCP18] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998,
<http://www.rfc-editor.org/info/bcp18>.
[BCP26] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008, <http://www.rfc-editor.org/info/bcp26>.
[BCP32] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS
Names", BCP 32, RFC 2606, June 1999,
<http://www.rfc-editor.org/info/bcp32>.
[BCP72] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552,
July 2003, <http://www.rfc-editor.org/info/bcp72>.
[CLUSTER] RFC Editor, "Clusters in the RFC Editor Queue",
<http://www.rfc-editor.org/cluster_def.html>.
[CMOS] Chicago Manual of Style, 16th ed. Chicago: University of
Chicago Press, 2010.
[FYI90] Malkin, G. and J. Reynolds, "FYI on FYI: Introduction to
the FYI Notes", FYI Notes, RFC 1150, March 1990.
Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360,
August 2011.
[IAB-FORM] IAB, "Format for RFCs in the IAB Stream",
<http://www.rfc-editor.org/rfc-style-guide/
iab-format.txt>.
[ID-GUIDE] IETF, "Guidelines to Authors of Internet Drafts",
<http://www.ietf.org/ietf-ftp/1id-guidelines.txt>.
[IETF-TRUST]
IETF Trust, "Trust Legal Provisions (TLP)",
<http://trustee.ietf.org/license-info/>.
[ISO_OBP] ISO, "Online Browsing Platform (OBP)",
<https://www.iso.org/obp/ui/>.
[ISO3297] Technical Committee ISO/TC 46, Information and
documentation, Subcommittee SC 9, Identification and
description, "Information and documentation -
International standard serial number (ISSN)",
September 2007.
[MIB-BOILER]
IETF OPS Area, "Boilerplate for IETF MIB Documents",
<http://www.ops.ietf.org/mib-boilerplate.html>.
[MIB-SEC] IETF OPS Area, "Security Guidelines for IETF MIB Modules",
<http://trac.tools.ietf.org/area/ops/trac/wiki/
mib-security>.
[REFS] IESG, "IESG Statement: Normative and Informative
References", <http://www.ietf.org/iesg/statement/
normative-informative.html>.
[RFC1311] Postel, J., "Introduction to the STD Notes", RFC 1311,
March 1992, <http://www.rfc-editor.org/info/rfc1311>.
[RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current
Practices", RFC 1818, August 1995,
<http://www.rfc-editor.org/info/rfc1818>.
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997, <http://www.rfc-editor.org/
info/rfc2223>.
[RFC2223bis]
Reynolds, J., Ed. and B. Braden, Ed. "Instructions to
Request for Comments (RFC) Authors", Work in Progress,
draft-rfc-editor-rfc2223bis-08, August 2004.
[RFC4844] Daigle, L., Ed., and Internet Architecture Board, "The RFC
Series and RFC Editor", RFC 4844, July 2007,
<http://www.rfc-editor.org/info/rfc4844>.
[RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams,
Headers, and Boilerplates", RFC 5741, December 2009,
<http://www.rfc-editor.org/info/rfc5741>.
[RFC6635] Kolkman, O., Ed., Halpern, J., Ed., and IAB, "RFC Editor
Model (Version 2)", RFC 6635, June 2012,
<http://www.rfc-editor.org/info/rfc6635>.
[STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005, <http://www.rfc-editor.org/
info/std66>.
[TERMS] RFC Editor, "Terms List",
<http://www.rfc-editor.org/styleguide.html>.
[YANG-SEC] IETF OPS Area, "yang module security considerations",
<http://trac.tools.ietf.org/area/ops/trac/wiki/
yang-security-guidelines>.Appendix A. Related Procedures
these procedures are related to applying and updating the RFC Style Guide 🧠
A.1. Dispute Resolution
there are competing reasons behind some of the rules in this Guide, and the RFC Editor picked the ones that work best for the Series 💅 sometimes an author disagrees with the RFC Production Center (RPC) about how Style Guide conventions get applied. in that case, the authors should talk through their concerns with the RPC 🫶 if the RPC and the authors can't agree, the RFC Series Editor will make the final call, with input from the appropriate stream-approving body 👑 if more resolution is needed, the dispute resolution process in the RFC Editor Model [RFC6635] gets followed 🔥
A.2. Returning an I-D to the Document Stream
if the RFC Editor decides a doc can't be edited without seriously risking a change to its technical meaning, or if the RFC Editor doesn't have the resources to edit it as much as it needs, it can be sent back to the stream-approving body. the request is to improve clarity, consistency, and/or readability of the doc 🌸 this isn't treated as a dispute with the author 💖
A.3. Revising This Document and Associated Web Pages
the RFC Series keeps evolving, and this document sticks to the fundamental, stable requirements every RFC has to meet 🦋 now and then the RFC Editor might offer less formal recommendations that authors can use at their discretion, and those live on the RFC Editor website "Guidelines for RFC Style" [STYLE-WEB] ✨
when a new recommendation about overall structure and formatting shows up, it gets published on that page and is accepted for a while before the RFC Editor decides whether it becomes one of the fundamental requirements in the RFC Style Guide or stays a less formal recommendation 🧚 how long that takes varies, partly depending on how often authors run into the guidance and apply it 🍓
IAB Members at the Time of Approval
- Jari Arkko (IETF Chair)
- Mary Barnes
- Marc Blanchet
- Joel Halpern
- Ted Hardie
- Joe Hildebrand
- Russ Housley
- Eliot Lear
- Xing Li
- Erik Nordmark
- Andrew Sullivan
- Dave Thaler
- Brian Trammell
Acknowledgements
this doc leans heavily on RFC 2223 [RFC2223] and [RFC2223bis], so a big thank-you to the authors of those documents for putting in the time and effort for the RFC Series 🥹🫶
- Robert T. Braden, USC Information Sciences Institute
- Joyce Reynolds
- Jon Postel
Contributors
- Alice Russo, RFC Production Center
Authors' Addresses
- Heather Flanagan, RFC Series Editor EMail:
rse@rfc-editor.org - Sandy Ginoza, RFC Production Center EMail:
rfc-editor@rfc-editor.org
📦 where this page comes from
- ietf: rfc7322 2014-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms