[rfc-i] Possiable April 1st contribution....

Warren Kumari warren at kumari.net
Fri Mar 23 08:12:10 PDT 2012


Still needs some work, if you think it is worth the trouble…

W

------------------


template                                                       W. Kumari
Internet-Draft                                                    Google
Intended status: Standards Track                               R. Bonica
Expires: September 10, 2012                             Juniper Networks
                                                           March 9, 2012


             Granular words to Indicate Requirement Levels
                       draft-wkumari-template-00

Abstract

   A common problem encountered in forming consensus on a document is
   the strength of the requirement.  For each recommendation or
   requirement a large amount of time is often spent discussing if a
   "should" or a "SHOULD" is appropriate, and these discussions can
   often become heated.  If additional levels of granularity could be
   provided, much animosity could be avoided, and much more time could
   be devoted to publishing useful documents.

   This document provides a means to provide additional levels of
   granularity to the requirements language in RFC 2119 and introduces
   two additional keywords.

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 http://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 September 10, 2012.

Copyright Notice

   Copyright (c) 2012 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



Kumari & Bonica        Expires September 10, 2012               [Page 1]
Internet-Draft              granular-rfc2119/                 March 2012


   (http://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 Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
     1.1.  Requirements notation . . . . . . . . . . . . . . . . . . . 3
   2.  Granularity within levels . . . . . . . . . . . . . . . . . . . 4
   3.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
   4.  Additional Keywords . . . . . . . . . . . . . . . . . . . . . . 5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
   6.  Security Considerations . . . . . . . . . . . . . . . . . . . . 6
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 6
   8.  Normative References  . . . . . . . . . . . . . . . . . . . . . 6
   Appendix A.  Changes / Author Notes.  . . . . . . . . . . . . . . . 6
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . . . 6





























Kumari & Bonica        Expires September 10, 2012               [Page 2]
Internet-Draft              granular-rfc2119/                 March 2012


1.  Introduction

   [RFC2119] provides a number of key words to be used in RFCs to
   indicate requirement levels.  It provides 3 main levels of
   requirements, in decreasing order or "strictness" these are MUST,
   SHOULD and MAY.  There are also negated forms of two of these (MUST
   NOT, SHOULD NOT), and various forms of some of the words (for
   example, RECOMMENDED is the adjective form of SHOULD), but these are
   sill only 3 major levels.  The lowercase versions of each of these
   terms is viewed more as a recommendations (or advice), and not a
   requirement.

   During the creation and review of Internet Drafts there is often a
   large amount of discussion regarding which requirement language
   should be used for a particular item withing the document.  These
   discussions are often taken very seriously by participants and often
   end up becoming very contentions and heated.  This has led to
   animosity and is often a huge time sink.

   Many of the discussions is disagreement over just how important a
   particular point is implementations of the protocol.  For example, if
   a specific error condition is uncounted and the document recommends
   that the error be logged, which is appropriate:

   o  If an error is detected in processing the additional data, an
      error SHOULD be logged so the operator can troubleshoot the error.
   o  If an error is detected in processing the additional data, an
      error should be logged so the operator can troubleshoot the error.

   Newcomers to the IETF may think that the difference between the two
   options is very minor and could not possibly cause discourse, but
   these sorts of discussion have destroyed friendships.  Different
   participants may have different use cases in mind for the protocol.
   White it may be appropriate for a server (or other device with large
   amounts of storage) to log errors for later review, the same advice
   many not work (or even be possible) for a small embedded device.

   At the root of the problem is the limited number of requirement
   levels, and so this document provides a means to provide granularity
   within each of the major levels.  This is intended to create a more
   harmonious IETF.

1.1.  Requirements notation

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].




Kumari & Bonica        Expires September 10, 2012               [Page 3]
Internet-Draft              granular-rfc2119/                 March 2012


2.  Granularity within levels

   From following many of the disagreements over which requirement
   language to use (and if the formal (RFC 2119) language should be used
   at all) it appears that the disagreements become more heated (and
   longer) depending on which particular level is being discussed.  In
   increasing order of discord the levels are:

   o  MAY
   o  MUST
   o  SHOULD

   It can be seen that number of letters in the requirements level word
   maps to the level of arguments created by the use of the word.
   Simply replacing each requirement level word with a single character
   (A, B, C) was briefly considered before it was realized that this was
   just a coincidence.  It is however a lucky coincidence as it means
   that we can use the length of the word to build in additional levels
   of requirements within each major level.

   The basic idea uses the observation that the lower cased version of
   each level (may, must, should) is viewed as less "strong" than the
   uppercase versions (MAY, MUST, SHOULD) with the length observations
   and encode (using binary) additional levels.

   By treating each letter position of the word as a bitmap, with an
   uppercase being a 1 and lowercase being a 0 we can create 6 (2^3 - 2)
   additional levels of granularity for the lest contentious requirement
   level (MAY), 14 additional levels for MUST, and a staggering 62
   additional levels for SHOULD.

   The bitmap should be treated as a "network order" field (with the
   most significant bit first).

   In order to demonstrate this, a worked example is provided:

   There is disagreement over whether an implementation is supposed to
   populate a specific field in a protocol unit.  One group of
   participants feels that this is entirely up to the implementors and
   that the word "should" explains this best.  Another group of
   participants feels that this will cause interoperability problems and
   that "SHOULD" is much more appropriate.  This discussion has been
   taking up a large amount of the working groups time and is becoming
   contentious.  Both sides raise good points, and both sides would be
   willing to compromise on something between the two extremes.  The
   working group decides that the interoperability concern has some
   validity, and so the compromise should favor the "SHOULD" side of the
   compromise.  The working group decides the "SHOULD" side of the



Kumari & Bonica        Expires September 10, 2012               [Page 4]
Internet-Draft              granular-rfc2119/                 March 2012


   argument is a little more than twice as strong as the "should" side,
   and so the granularity of the requirements text should reflect this

   With 64 granularity levels available for SHOULD, a ratio of 52:12 in
   favor of SHOULD is deemed appropriate. 52 decimal in binary is 110100

      5 4 3 2 1 0
     +-+-+-+-+-+-+
     |1|1|0|1|0|0|
     +-+-+-+-+-+-+
   Now, we simply overlay 110100 on the word "should", replacing the
   lowercase letters with uppercase letters where ever there is a 1.
      5 4 3 2 1 0
     +-+-+-+-+-+-+
     |1|1|0|1|0|1|
     +-+-+-+-+-+-+
     |S|H|o|U|l|d|
     +-+-+-+-+-+-+

   This provides us with our final result, "SHoUld" -- this can easily
   be seen be the reader as being somewhere between a "SHOULD" and a
   "should", and weighted towards the former.


3.  Examples

   During discussions on the draft,it was felt that "This technique
   should only be used on April 1st" was to weak, but "This technique
   SHOULD only be used on April 1st" was much too strong, so the authors
   settled on "This document shouLD only be used on April 1st."  This
   allowed us to stop bickering and go have a tasty dinner.


4.  Additional Keywords

   This section introduces two additional keywords, for use in special
   situations.

   1.  THOU SHALL / SHALL NOT These words indicate requirements that are
       included purely for religious reasons.  An example of where these
       mAy be used is in any draft that discusses NAT, Path MTU
       discovery or buffering.
   2.  SHALST The term "SHALST" should be used to indicate requirement
       that is so poorly stated that nobody will ever be able to figure
       out whether or not you are compliant.  This is often appropriate
       for drafts that have been introduced to the IETF from other
       standard development organizations, or vendors who one secretly
       believes don't really want interoperable implementations.



Kumari & Bonica        Expires September 10, 2012               [Page 5]
Internet-Draft              granular-rfc2119/                 March 2012


5.  IANA Considerations

   While this document requests no actions from the IANA, it is expected
   that these terms may show up in future document's IANA Considerations
   sections, and so the IANA should be aware of their meanings.


6.  Security Considerations

   This document aims to remove much of the animosity from some of the
   more contentious discussions, and in doing so will allow participants
   to focus more on writing better drafts.  While it may be a stretch,
   it should also avoid physical violence (like tugging of beards) and
   so will make participants feel more secure.


7.  Acknowledgements

   The authors wish to thank all of the participants who have been
   involved in SHOULD vs should discussions for providing the impetus
   for this draft...


8.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.


Appendix A.  Changes / Author Notes.

   [RFC Editor: Please remove this section before publication ]

   From -00 to -01.

   o  Nothing changed in the template!


Authors' Addresses

   Warren Kumari
   Google
   1600 Amphitheatre Parkway
   Mountain View, CA  94043
   US

   Email: warren at kumari.net




Kumari & Bonica        Expires September 10, 2012               [Page 6]
Internet-Draft              granular-rfc2119/                 March 2012


   Ron Bonica
   Juniper Networks
   Sterling, Virginia  20164
   USA

   Email: rbonica at juniper.net













































Kumari & Bonica        Expires September 10, 2012               [Page 7]

--
Don't be impressed with unintelligible stuff said condescendingly.
    -- Radia Perlman.







More information about the rfc-interest mailing list