idnits 2.17.1 draft-leiba-rfc2119-update-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC2119, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. (Using the creation date from RFC2119, updated by this document, for RFC5378 checks: 1997-03-01) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 09, 2016) is 2818 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCxxxx' is mentioned on line 134, but not defined Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Leiba 3 Internet-Draft Huawei Technologies 4 Updates: 2119 (if approved) August 09, 2016 5 Intended status: Best Current Practice 6 Expires: February 08, 2017 8 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words 9 draft-leiba-rfc2119-update-00 11 Abstract 13 RFC 2119 specifies common key words that may be used in protocol 14 specifications. This document aims to reduce the ambiguity by 15 clarifying that only UPPERCASE usage of the key words have the 16 defined special meanings, and by deprecating some versions of the key 17 words. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on February 08, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (http://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 1. Introduction 51 RFC 2119 specifies common key words, such as "MUST", "SHOULD", and 52 "MAY", that may be used in protocol specifications. It says that 53 those key words "are often capitalized," and that has caused 54 confusion about how to interpret non-capitalized words such as "must" 55 and "should". 57 This document updates RFC 2119 by clarifying that only UPPERCASE 58 usage of the key words have the defined special meanings. It also 59 reduces wording conflicts by deprecating some synonymous key words. 60 This document will become part of BCP 14 when it is approved. [[RFC- 61 Editor: Please change the previous sentence to "This document is part 62 of BCP 14."]] 64 1.1. Some Notes for Reviewers (not for publication) 66 [[RFC-Editor: Please remove this section before publishing.]] 68 This update is intentionally small and focused, and quite 69 intentionally updates, but does not replace, RFC 2119. The author 70 considers it important to retain the reference to RFC 2119 because of 71 the general familiarity with the number, and to phase in the use of 72 "BCP 14". Note, though, that the References section uses the RFC 73 numbers, not the BCP number. This is because is needs to be clear 74 when a document has adopted this update, and the dual reference to 75 RFC 2119 *and* this document gives that clarity. 77 The point has been made by some that having case be significant to 78 the meanings of words is unusual and may be a bad idea. There is 79 specific concern about causing confusion to readers whose native 80 languages do not have a distinction between upper and lower case 81 (consider Chinese and Hebrew, for example). The author believes this 82 has been discussed and addressed, and that those maintaining this 83 point are in the rough. That said, it may still be worth continuing 84 the discussion a bit. 86 There have been suggestions that while we're here we should consider 87 a broader BCP 14 update that also talks about proper use of the key 88 words, when they should not be used, avoiding overuse, and so on. 89 The author agrees, but thinks is best to keep that as a separate 90 effort, as coming to consensus on such an update is likely to be much 91 more difficult, and is likely to take much longer. 93 2. Clarifying Capitalization of Key Words 95 The following change is made to [RFC2119]: 97 === OLD === 98 In many standards track documents several words are used to signify 99 the requirements in the specification. These words are often 100 capitalized. This document defines these words as they should be 101 interpreted in IETF documents. Authors who follow these guidelines 102 should incorporate this phrase near the beginning of their document: 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in RFC 2119. 108 === NEW === 109 In many standards track documents several words are used to signify 110 the requirements in the specification. These words are often 111 capitalized, as shown below, but they do not have to be. This 112 document defines how these words are interpreted in IETF documents 113 when the words are capitalized. 115 o These words can be used as defined here, but it is not required 116 that they be. Specifically, normative text does not require the 117 use of these key words. They are used for clarity and consistency 118 when that is what's wanted, but a lot of normative text does not 119 use them, and does not need to use them. 121 o The words have the meanings specified herein only when they are 122 capitalized. 124 o When these words are not capitalized, they have their normal 125 English meanings; this document has nothing to do with them. 127 Authors who follow these guidelines should incorporate this phrase 128 near the beginning of their document: 130 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and 131 "MAY" in this document are to be interpreted as described in 132 BCP 14 [RFC2119],[RFCxxxx] when, and only when, they appear 133 capitalized, as shown. 135 === END === 137 [[RFC Editor: Please replace "RFCxxxx", above, with a reference to 138 this RFC number, and remove this note.]] 140 3. Deprecating some synonymous key words 142 To reduce the number of reserved key words, the following key words 143 are deprecated, and no longer have special meanings defined by BCP 144 14: 146 REQUIRED, SHALL, SHALL NOT, RECOMMENDED, NOT RECOMMENDED, OPTIONAL 148 4. IANA Considerations 150 There are no IANA considerations for this document. 152 5. Security Considerations 153 This document is purely procedural, and there are no related security 154 considerations. 156 6. Normative References 158 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 159 Requirement Levels", BCP 14, RFC 2119, March 1997. 161 Author's Address 163 Barry Leiba 164 Huawei Technologies 166 Phone: +1 646 827 0648 167 Email: barryleiba@computer.org 168 URI: http://internetmessagingtechnology.org/