Subject: Making RFC2119 key language easier to Protocol Readers

From: Abdussalam Baryun <[email-masked]>
Date: Fri, 4 Jan 2013 21:51:06 +0100

>> formalization of the description language, and I like the English
>> prose. But it raises process questions for the IETF as a whole:
>>
>> Are we deliberately evolving our language to use RFC 2119 terms as the
>> principle verbs  of a formal specification language?

Is it *our language* or our specification language?

I agree that we use in IETF documents the English language but don't
think it is equal/close to all WORLD's language(s), so using RFC2119
will help programmers to read who may like the spoken language, but
like most the specification coding  language(s). However, the
specification/protocol language reader needs to be clear and in an
easy language. I think in the IETF the coding languages is OUR
language not only English.

AB

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 09:31:07 +0100

Hi Hector,

I like your method, which beleive is the reason why the RFC2119 is
great help for implementors. As I mentioned before if the protocol
specification is long and complicated no doubt its language may make
it more difficult to readers or writters. Therefore, it will be nice
if the IETF surveys this matter as you and Scott suggested.

Thanking you
Abdussalam Baryun

+++++++++++++++++++++++++++
Date: Fri, 04 Jan 2013 22:24:50 -0500
From: Hector Santos <hsantos at isdg.net>
To: Scott Brim <swb at internet2.edu>
Sub:Re: I'm struggling with 2219 language again

We have implemented numerous protocols since the 80s. I have a
specific method of approaching a new protocol implementation which
allows for fastest implementation, testing proof of concept and above
all minimum cost. Why bother with the costly complexities of
implementing SHOULDs and MAYs, if the minimum is not something you
want in the end anyway?

A good data point is that for IP/Legal reasons, we do not use other
people's code if we can help it and in the early days, open source was
not as wide spread or even acceptable at the corporate level. In other
words, it was all done in-house, purchased or nothing. I also believe
using other people's code has a high cost as well since you don't have
an in-house expert understanding the inner workings of the externally
developed software.
o Step 1 for Protocol Implementation:

Look for all the MUST protocol features. This includes the explicit
ones and watchful of semantics where its obviously required or things
will break, perhaps it fell thru the crack.

An important consideration for a MUST is that operators are not given
the opportunity to disable these protocol required features. So from a
coding standpoint, this is one area you don't have to worry about
designing configuration tools, the UI, nor including operation
guidelines and documentation for these inherent protocol required
features.

This is the minimum coding framework to allow for all inteop testing
with other software and systems.

The better RFC spec is the one that has documented a checklist, a
minimum requirement summary table, etc. Good example is RFC 1113 for
the various internet hosting protocols. I considered RFC 1123 the
"bible!"

Technical writing tip: Please stay away from verbosity especially of
subjective concepts and please stop writing as if everyone is stupid.
    I always viewed the IETF RFC format as a blend of two steps
    of the SE process - functional and technical specifications.
    Functional specs tell us what we want and technical specs
    tell us how we do it.  So unless a specific functional requirements
    RFC was written, maybe some verbosity is needed but it should
    be minimized.

Generally, depending on the protocol, we can release code just on
using MUST requirements - the bottom line framework for client/server
communications. Only when this is completely successfully, can your
implementation consider moving on at extending the protocol
implementation with additional SHOULD, MAY features and its optional
complexities.
o Step 2

Look for the SHOULDs. This is the candies of the protocol. If the
SHOULD is really simple to implement, it can be lumped in with step 1.

I know many believe a SHOULD are really a MUST as an alternative
method perhaps - different version of MUST to be done nonetheless.

However, I believe these folks play down an important consideration
for implementing SHOULD based protocol features:
   Developers need to offer these as options to deployment operators.

In other words, if the operator can not turn it off then a SHOULD was
incorrectly used for a MUST which is required with no operator option
to disable.
o Step 3

Look for the MAYs. Very similar to SHOULD, a good way to consider a
SHOULD is as a default enabled (ON out of the box) option and a MAY as
a default disabled (OFF out of the box) option.
Summary:

  MUST   - required, no operator option to disabled. Of course,
           its possible to have a hidden, undocumented switch
           for questionable stuff.

  SHOULD - good idea, recommended. if implemented, enabled it
           out of the box.

  MAY    - similar to SHOULD, does not have to be enabled out
           of box.

In both cases for SHOULD and MAY, the operator can turn these protocol
features off/on. For a MUST, the operator can not turn the MUST
feature. These SHOULD/MAY features are documented for operators and
support.

One last thing, I believe in a concept I call CoComp - Cooperative
Competition, where all competitive implementators, including the
protocol technology leader all share a common framework for a minimum
protocol generic to all parties and the internet community. It is
least required to solve the problem or provide a communication avenue.
All else, the SHOULDs, the MAYs, is added value for competing
implementators. It generally is what differentiate the various
implementators software.

I personally believe it is doable to write a new RFC that describe a
guideline for protocol development that will minimize conflicts at
many levels. Of course, a major part of that is good technical writing
skills in principle and the ability to extract and describe what the
protocol framework is, which brings it all back to the original issue
using the proper communications verbiage to describe a protocol.
--
HLS

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 09:36:55 +0100

>IMO, too many specs seriously overuse/misuse 2119 language, to the
detriment of readability, common sense, and reserving the terms to
bring attention to those cases where it really is important to
highlight an important point that may not be obvious to a casual
reader/implementor.

also to highlight an important point that may not be obvious to
imlementors which are non-English speakers/writers.

AB

---

From: Mikael Abrahamsson <[email-masked]>
Date: Sat, 5 Jan 2013 09:39:18 +0100 (CET)

As an operator, I purchase equipment and need to write RFQs. I would like 
to able to ask more than "does the product implement RFC <whatever>", I 
want to also ask "Please document all instances where you did not follow 
all MUST and SHOULD, and why".

Otherwise I think there needs to be better definition of what it means to 
"implement" or "support" an RFC when it comes to completness and what this 
means as per following SHOULD and MAY.

-- 
Mikael Abrahamsson    email: [email-masked]

---

From: Mikael Abrahamsson <[email-masked]>
Date: Sat, 5 Jan 2013 09:43:31 +0100 (CET)

On Sat, 5 Jan 2013, Mikael Abrahamsson wrote:

> Otherwise I think there needs to be better definition of what it means 
> to "implement" or "support" an RFC when it comes to completness and what 
> this means as per following SHOULD and MAY.

Also what it means following things in it that is not RFC2119 language.

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 09:54:45 +0100

(was Re: I'm struggling with 2219 language again)

>> Where you want to use MUST is where an implementation might be tempted
>> to take a short cut -- to the detriment of the Internet -- but could
>> do so without actually breaking interoperability. A good example is
>> with retransmissions and exponential backoff. You can implement those
>> incorrectly (or not at all), and still get "interoperability". I.e.,
>> two machines can talk to each other. Maybe you don't get "good"
>> intereoperability and maybe not great performance under some
>> conditions, but you can still build an interoperabile implementation.

>Sadly true.

We can fix that, by discussing it further, or as Scott mentioned the survey [*]

>> two machines can talk to each other. Maybe you don't get "good"
>> intereoperability and maybe not great performance under some
>> conditions, but you can still build an interoperabile implementation.

As machines reads and writes may depend on conditions, I don't think
it is true that you can still interoperabile implementation by
ignoring using/documenting requirement keys language (i.e. all common
keys of all languages).

AB

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 10:00:21 +0100

We can fix that, by discussing it further, or as Scott mentioned make
a survey within IETF [*]

[*] http://www.ietf.org/mail-archive/web/ietf/current/msg76582.html

AB

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 10:04:36 +0100

I totally agree with you,

AB

+++
As an operator, I purchase equipment and need to write RFQs. I would
like to able to ask more than "does the product implement RFC
<whatever>", I want to also ask "Please document all instances where
you did not follow all MUST and SHOULD, and why".

Otherwise I think there needs to be better definition of what it means
to "implement" or "support" an RFC when it comes to completness and
what this means as per following SHOULD and MAY.
--
Mikael Abrahamsson    email: swmike at swm.pp.se

---

From: Abdussalam Baryun <[email-masked]>
Date: Sat, 5 Jan 2013 10:08:32 +0100

Hi Mikael

>Also what it means following things in it that is not RFC2119 language.

It will mean, you should understand me/english/ietf/procedure even if
I don't have to explain, and you need to understand English well even
if you are a great implementor or great programming language speaker.

AB
===

---

From: Mikael Abrahamsson <[email-masked]>
Date: Sat, 5 Jan 2013 10:13:03 +0100 (CET)

> if you are a great implementor or great programming language speaker.

The problem here is that I want them to pay back some of the money (or 
take back the equipment totally and give back all money) for breach of 
contract, when I discover that they haven't correctly (as in intention and 
interop) implemented the RFC they said they said they were compliant in 
supporting.

Ianal, but it feels that it should easier to do this if there are MUST and 
SHOULD in there and I asked them to document all deviations from these.

---

From: John C Klensin <[email-masked]>
Date: Sat, 05 Jan 2013 11:03:05 -0500

--On Saturday, January 05, 2013 10:13 +0100 Mikael Abrahamsson
<[email-masked]> wrote:

> The problem here is that I want them to pay back some of the
> money (or take back the equipment totally and give back all
> money) for breach of contract, when I discover that they
> haven't correctly (as in intention and interop) implemented
> the RFC they said they said they were compliant in supporting.
> 
> Ianal, but it feels that it should easier to do this if there
> are MUST and SHOULD in there and I asked them to document all
> deviations from these.

Folks, there is a long-term tension in almost every standards
body (at least those who notice) between

	-- a specification whose primary purpose is guidance for
	implementers and, in particular, implementers who intend
	to do the best job possible to make things work together.
	
	-- a specification whose primary purpose is to set
	boundaries for what constitutes a conforming
	implementation so that, as Mikael suggests, one can hold
	those whose implementations do not fall within those
	boundaries can be help accountable legally and/or
	financially.

The traditional position of the IETF is not only that the first
is much more important than the second, but that the test of a
successful specification is interoperable implementations.   If
a pair of implementations do not interoperate, our assumption is
that something is broken, be it implementation 1, implementation
2, or the spec.  Indeed, our old "Draft Standard" requirements
took it as at least a default that the problem lay in the spec,
in part because we weren't very worried about bad-faith
implementations.

Similarly, if there are a half-dozen implementations, all of
which are widely deployed and interoperate smoothly but disagree
with the spec, we usually look on the spec with suspicion and
fix it to conform to those implementations.   In an organization
following the second model, the spec is paramount and all six of
those implementations are wrong (and can be held accountable by
third parties for being wrong).

In the IETF, that tension shows up in many ways.  There are not
just arguments about the use of 2119 terms, but statements like
"the audience for IETF Standards and the RFC Series is
implementers".  Those statements are hotly debated because,
among other things, our documents -- like it or not-- are used
in procurements and, if there are problems, in precisely the way
Mikael describes.   Some of them work better in those contexts
than others.

Another tension is that, while "interoperability" is a good
criterion for some specs, it is less so for others.  "If you do
X, things won't interoperate" can be a valid and important
statement, but so can "If you do Y, things may interoperate
perfectly well in the 'they work together' sense, but there will
be one operational mess after another".  A very narrow reading
of 2119 would permit a MUST NOT for the first case, but not even
a SHOULD NOT for the second because the problem has nothing to
do with a narrow reading of "interoperability".  This is the
reason why some of us have never particularly liked the
interoperability-linked language of 2119.  Its intent, I think,
is to shift the concern toward the first model above and away
from the second but the side-effect of the language chosen has
been to create arguments against strong requirements for
operational quality and minimum implementation quality --
requirements that are perfectly consistent with the first model
above (and possibly even helpful for the second).  

It is also why some of us have argued for years that invocation
of 2119 and its definitions should be optional.  But "optional"
has often morphed in practice -- and with IESGs were were, IMO,
more interested in rules and their rigid interpretation than in
sensible and flexible understanding of particular situations and
needs -- into "optional only in theory" or "optional only if one
can prove to the satisfaction of the most rigid AD that it is
absolutely necessary".

And, again, that is further complicated by the observation that
IETF Standards are used for procurement and even for litigation
about product quality.   We either need to accept that fact and,
where necessary, adjust our specification style to match or we
run the risk of bodies springing up who will profile our
Standards, write procurement-quality conformance statements for
their profiles, and become, de facto, the real standards-setter
for the marketplace (and obviously do so without any element of
IETF consensus).  

Aside but really, IMO, at the core of these sorts of
discussions: Telling people what the IETF says they can't do is
pretty useless, at least until we organize the Protocol Police
to enforce our positions and, ideally, the Protocol Army and
Gallows to make the Protocol Police credible.  If people think
they need to do something, they will do it without allowing us
to comment.  And, if they think they need to standardize
whatever they are doing that we've told them they can't, they
will just find another forum.  We then end up complaining about
how all those nasty people are modifying or extending our
standards without our permission and that is another activity
that may be satisfying but is rarely productive.

    best.
     john

---

From: Hector Santos <[email-masked]>
Date: Sat, 05 Jan 2013 11:37:46 -0500

Keep in mind only a STD is a "real" standard. A RFC is still only a 
recommendation,  a guideline.  What makes it a "pseudo-standard" is 
the # of implementations, how wide spread it is and foremost IMO, how 
much embedded it is so that a change has a negative impact.  At that 
point, an RFC not having a STD status probably doesn't matter any more.

At best, you might be able to sue for malpractice (failing to do what 
most experts in field would be doing) in cases where there is provable 
harm caused by the neglect to implement a well known practice. But 
only maybe getting your money back is realistic. :)

ikael Abrahamsson wrote:
> contract, when I discover that they haven't correctly (as in intention 
> and interop) implemented the RFC they said they said they were compliant 
> in supporting.
> 
> Ianal, but it feels that it should easier to do this if there are MUST 
> and SHOULD in there and I asked them to document all deviations from these.
> 

-- 
HLS

---

From: Melinda Shore <[email-masked]>
Date: Sat, 05 Jan 2013 13:53:38 -0900

On 1/4/13 11:39 PM, Mikael Abrahamsson wrote:
> <whatever>", I want to also ask "Please document all instances where you
> did not follow all MUST and SHOULD, and why".
> 

I think being clear about who our constituencies are and what they
need is probably key to coming to any sort of agreement on any of this.
We've often complained about the lack of operator participation and
Mikael's comments may be an example the consequences of that - that we
don't fully understand how our documents are being used.

That said, frankly I've tended to assume that language in standards
documents is normative unless otherwise specified, and that highly
legalistic language is difficult to read.  On a third hand it wouldn't
be a small thing if non-native English speakers had an easier time with
our documents if every single normative thing in document is flagged
through the use of 2119 language.

So, basically where that leaves me is: 1) language in standards-track
documents is already normative by default; 2) however, if inserting
2119 language in all standards-track documents will make documents more
useful to people who actually run networks and/or clearer to people
whose first language is not English, it's probably worth tightening up
our language.

Melinda

---

From: Dean Willis <[email-masked]>
Date: Tue, 15 Jan 2013 00:16:14 -0600

On Jan 5, 2013, at 3:13 AM, Mikael Abrahamsson <[email-masked]> wrote:

> The problem here is that I want them to pay back some of the money (or take back the equipment totally and give back all money) for breach of contract, when I discover that they haven't correctly (as in intention and interop) implemented the RFC they said they said they were compliant in supporting.
> 
> Ianal, but it feels that it should easier to do this if there are MUST and SHOULD in there and I asked them to document all deviations from these.
> 

What about when the MUST and SHOULD are in the context of "Alice MUST send a request message to Bob" and you don't have users named Alice or Bob?

Seriously -- at what point does replacing all action verbs with 2119 language make the protocol spec LESS useful for compliance certification?

--
Dean

---

From: Dean Willis <[email-masked]>
Date: Tue, 15 Jan 2013 00:19:23 -0600

> for the marketplace (and obviously do so without any element of

I'm not sure that's not a good thing. Witness for example the work SIP Forum has done with the SIPConnect standards, which have made it MUCH easier to order a box that will work with a SIP Trunking service.

--
Dean

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 15 Jan 2013 08:02:01 +0000

On 15/01/2013 06:16, Dean Willis wrote:
...
> Seriously -- at what point does replacing all action verbs with 2119 language make the protocol spec LESS useful for compliance certification?

Wrong question. What we (the IETF) care about is the existence of interoperable
implementations, not mathematical compliance.

If you ask "at what point does replacing all action verbs with 2119 language make
the protocol spec LESS useful for coding interoperable versions?", I think
the answer will be something like "when it makes the spec so ugly and
difficult to read that people get things wrong as a result."

> I'm not sure that's not a good thing. Witness for example the work SIP Forum has done with the SIPConnect standards, which have made it MUCH easier to order a box that will work with a SIP Trunking…

I think there are cases of standards of extreme complexity, such as
SIP, where such profiles may be useful, because otherwise interoperability
cannot be achieved. But perhaps the lesson for the IETF here is slightly
different - don't design standards which allow that degree of complexity
in the first place.

    Brian

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Tue, 15 Jan 2013 03:21:41 -0800

On 01/15/2013 12:02 AM, Brian E Carpenter wrote:
> On 15/01/2013 06:16, Dean Willis wrote: ...
>> Seriously -- at what point does replacing all action verbs with 2119
>> language make the protocol spec LESS useful for compliance
>> certification?
> 
> Wrong question. What we (the IETF) care about is the existence of
> interoperable implementations, not mathematical compliance.
> 
> If you ask "at what point does replacing all action verbs with 2119
> language make the protocol spec LESS useful for coding interoperable
> versions?", I think the answer will be something like "when it makes the
> spec so ugly and difficult to read that people get things wrong as a
> result."
> 
>>>> And, again, that is further complicated by the observation that IETF
>>>> Standards are used for procurement and even for litigation about
>>>> product quality.   We either need to accept that fact and, where
>>>> necessary, adjust our specification style to match or we run the risk
>>>> of bodies springing up who will profile our Standards, write
>>>> procurement-quality conformance statements for their profiles, and
>>>> become, de facto, the real standards-setter for the marketplace (and
>>>> obviously do so without any element of IETF consensus).
>> 
>> I'm not sure that's not a good thing. Witness for example the work SIP
>> Forum has done with the SIPConnect standards, which have made it MUCH
>> easier to order a box that will work with a SIP Trunking service.
> 
> I think there are cases of standards of extreme complexity, such as SIP,
> where such profiles may be useful, because otherwise interoperability 
> cannot be achieved.

I would not call SIP a standard of extreme complexity, but anyway there is
more and more protocols on a similar complexity - just two protocols that I am
working with currently - RSTP 2.0 and RELOAD - are of similar complexity.

> But perhaps the lesson for the IETF here is slightly different - don't
> design standards which allow that degree of complexity in the first place.

There is no simple solution to a complex problem, so as the problems we try to
solve increase in complexity, so are our solutions to them.  But perhaps you
are right in a way.  Perhaps the problem is simply that RFC 2119, and the
issues I and other see with the approach in using as little of the keywords as
possible, was designed for a time when problems - and solutions - were
simpler.  Perhaps RFC 2119 imposes an upper limit on the complexity that a
protocol developed with it can reach, and we are just hitting this threshold
more and more often.

I am not saying that it is a bad thing - I certainly like simple protocols,
but perhaps the IETF is simply the wrong place for developing complex protocols.

- -- 
Marc Petit-Huguenin
Email: [email-masked]
Blog: http://blog.marc.petit-huguenin.org
Profile: http://www.linkedin.com/in/petithug

---

From: John C Klensin <[email-masked]>
Date: Tue, 15 Jan 2013 09:02:01 -0500

--On Tuesday, January 15, 2013 00:19 -0600 Dean Willis
<[email-masked]> wrote:

>> And, again, that is further complicated by the observation
>> that IETF Standards are used for procurement and even for
>> litigation about product quality.   We either need to accept
>> that fact and, where necessary, adjust our specification
>> style to match or we run the risk of bodies springing up who
>> will profile our Standards, write procurement-quality
>> conformance statements for their profiles, and become, de
>> facto, the real standards-setter for the marketplace (and
> I'm not sure that's not a good thing. Witness for example the
> work SIP Forum has done with the SIPConnect standards, which
> have made it MUCH easier to order a box that will work with a
> SIP Trunking service.

Dean,

Historically, there are many cases where certification
arrangements have worked out well, many cases where they have
worked out badly, and many cases where evaluation of the
certification process has, itself, been controversial.   That
really isn't the point.  The issue is locus of authority in
practice because, if certification is important in the
marketplace, then the real standard is ability to conform to and
pass certification, not conformance to the published Standard or
the ability of implementations built to that published Standards
to interoperate.  

One can imagine a certification test that fatefully follows the
published Standard and verifies every feature and requirement
_and_ that that either the published Standard is well enough
written to not allow alternate interpretations that would not
interoperate or the certification process includes adequate
interoperability tests.  In that case, the difference between
"conform to (i.e., pass) certification test" and "conform to
published Standard" is mostly a matter of aesthetics and
perceptions of control.   

However, IETF has often been very concerned about change control
and, no matter how good everyone's intentions, successful
certification activities often switch the locus of that control
(sometimes, so do unsuccessful ones and ones that are mandated
by some authority).  In addition, some people would suggest that
the near-perfect certification test outlined above bears a
strong resemblance to provably-correct computer programs: the
proofs are possible and work well for very simple cases,
primarily those that are designed an constructed with proof in
mind and not for more complex and organic situations.

    john

---

From: John C Klensin <[email-masked]>
Date: Tue, 15 Jan 2013 09:18:02 -0500

--On Tuesday, January 15, 2013 08:02 +0000 Brian E Carpenter
<[email-masked]> wrote:

> I think there are cases of standards of extreme complexity,
> such as SIP, where such profiles may be useful, because
> otherwise interoperability cannot be achieved. But perhaps the
> lesson for the IETF here is slightly different - don't design
> standards which allow that degree of complexity in the first
> place.

Yes.  And, if the certification test actually represents a
profile, then either:

(1) Implementations and certification tests that match a
different profile won't interoperate with this first one.  That
is a problem to which a number of ITU and ISO/IEC JTC1 standards
have fallen victim.

(2) If the profile represented by the tests is really widely
accepted as being the important core of the standard and IETF
believes in its own principles, we should immediately update and
replace the Standard to remove everything not included in that
profile, accomplishing an approximation to Brian's (and my)
lower-complexity specification the hard way.

    john

p.s. that latter issue raises another question about
draft-farrell-ft-03.txt and the associated Last Call.  The
ability to implement a spec does not demonstrate that it
contains the minimum level of complexity needed to do the job.
Would "more complex than necessary and therefore in need of
further work" be an acceptable Last Call comment and subject to
a DISCUSS within the intent of that document?