Subject: [yang-doctors] SHOULD statements in rfc6087bis

From: Mahesh Jethanandani <[email-masked]>
Date: Mon, 21 May 2018 08:32:15 -0700

In the guidelines to YANG authors, rfc6087bis has outlined expectations from authors by the use of SHOULD and MUST statements. I imagine, that they roughly translate to warnings and errors reported by different tools. What is not clear, reading the draft is to what extent these guidelines need to be followed, particularly as the document gets ready for publication.

This is particularly true for SHOULD statements. Is the expectation that we could be publishing a document with warnings reported by yangvalidator? A corollary to that is, if warnings do not need to be fixed, why do we bother reporting them?

Thanks.

Mahesh Jethanandani
[email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Mon, 21 May 2018 08:49:32 -0700

On Mon, May 21, 2018 at 8:32 AM, Mahesh Jethanandani <
[email-masked]> wrote:

> In the guidelines to YANG authors, rfc6087bis has outlined expectations
> from authors by the use of SHOULD and MUST statements. I imagine, that they
> roughly translate to warnings and errors reported by different tools. What
> is not clear, reading the draft is to what extent these guidelines need to
> be followed, particularly as the document gets ready for publication.
>
> This is particularly true for SHOULD statements. Is the expectation that
> we could be publishing a document with warnings reported by yangvalidator?
> A corollary to that is, if warnings do not need to be fixed, why do we
> bother reporting them?
>
>
SHOULD means the same as other types of text.
The reviewers have to consider each case and decide if it applies.

The IETF has no place telling tool makers what to flag as a warning.
A compiler reports language usage that may not be what the author intended.
A smart engineer will examine the warning and determine if it needs to be
addressed.

Thanks.
> [email-masked]
Andy

> _______________________________________________
> yang-doctors mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/yang-doctors
>

---

From: Benoit Claise <[email-masked]>
Date: Mon, 21 May 2018 16:59:50 +0100

Mahesh,

Some argued that RFC6087 was informational, hence not following SHOULD 
was fine.
RFC6087bis is a BCP. This makes the difference, so the tooling must 
follow the SHOULD.

Regards, Benoit
> .

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 21 May 2018 18:14:35 +0200 (CEST)

> The reviewers have to consider each case and decide if it applies.

I agree.  This was the intention with the MUST vs. SHOULD language in
6087(bis).

FWIW, pyang gives an error if a MUST is not followed, but a warning if
a SHOULD is not followed.

> A smart engineer will examine the warning and determine if it needs to be

Yes.

/martin

---

From: Mahesh Jethanandani <[email-masked]>
Date: Mon, 21 May 2018 12:27:46 -0700

In summary, what I am gathering from this discussion is that it is ok for us to publish an IETF draft that contains a normative YANG module, and that YANG module have warnings (SHOULD) reported by pyang or other tools. But if the same module has an error (MUST) reported by the tools, the error has to be fixed.

Thanks.

> On May 21, 2018, at 9:14 AM, Martin Bjorklund <[email-masked]> wrote:
> 

Mahesh Jethanandani
[email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Mon, 21 May 2018 12:35:54 -0700

Hi,

My understanding is that SHOULD means you need a good reason not to follow
the guideline.

Andy

On Mon, May 21, 2018 at 12:27 PM, Mahesh Jethanandani <
[email-masked]> wrote:

> In summary, what I am gathering from this discussion is that it is ok for
> us to publish an IETF draft that contains a normative YANG module, and that
> YANG module have warnings (SHOULD) reported by pyang or other tools. But if
> the same module has an error (MUST) reported by the tools, the error has to
> be fixed.
>
> Thanks.
>

---

From: Benoit Claise <[email-masked]>
Date: Mon, 21 May 2018 20:49:13 +0100

On 5/21/2018 8:35 PM, Andy Bierman wrote:
> Hi,
>
> My understanding is that SHOULD means you need a good reason not to 
> follow the guideline.
That's my understanding as well. At least this is the intent behind a 
SHOULD in a BCP.

Regards, B.
>
>
> Andy
>
>
> On Mon, May 21, 2018 at 12:27 PM, Mahesh Jethanandani 
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>     In summary, what I am gathering from this discussion is that it is
>     ok for us to publish an IETF draft that contains a normative YANG
>     module, and that YANG module have warnings (SHOULD) reported by
>     pyang or other tools. But if the same module has an error (MUST)
>     reported by the tools, the error has to be fixed.
>
>     Thanks.
>
>     > On May 21, 2018, at 9:14 AM, Martin Bjorklund <[email-masked]
>     <mailto:[email-masked]>> wrote:
>     >
>     > Andy Bierman <[email-masked] <mailto:[email-masked]>> wrote:
>     >> [email-masked] <mailto:[email-masked]>> wrote:
>     >>
>     >>> mjethanandani@gmail..com <mailto:[email-masked]>
>     >>>
>     >>>
>     >> Andy
>     >>
>     >>
>     >>> [email-masked] <mailto:[email-masked]>
>     <https://www.ietf.org/mailman/listinfo/yang-doctors>
>     >>>
>
>     Mahesh Jethanandani
>     [email-masked] <mailto:[email-masked]>
>
>
>
>

---

From: Andy Bierman <[email-masked]>
Date: Mon, 21 May 2018 12:51:33 -0700

> That's my understanding as well. At least this is the intent behind a

3 <https://tools.ietf.org/html/rfc2119#section-3>. SHOULD   This word,
or the adjective "RECOMMENDED", mean that there
   may exist valid reasons in particular circumstances to ignore a
   particular item, but the full implications must be understood and
   carefully weighed before choosing a different course.

Regards, B.

Andy

>> >>> mjethanandani@gmail..com <[email-masked]>
>> >>>
>> >>>
>> >> Andy
>> >>
>> >>
> yang-doctors mailing [email-masked]://www.ietf.org/mailman/listinfo/yang-doctors
>
>
>

---

From: Mahesh Jethanandani <[email-masked]>
Date: Mon, 21 May 2018 21:03:43 -0700

It seems that we agree that even though rfc6087bis is a BCP, that authors need a good reason not to fix warnings (SHOULD) in the YANG model.

The reason I asked the question in the first place is because of draft-ietf-netconf-nmda-netconf, which currently has one warning reported against the YANG model. 

[email-masked]:
pyang 1.7.5: pyang --verbose --ietf -p {libs} {model}:
[email-masked]:205: warning: RFC 6087: 4.10,4.12: statement "enum" should have a "description" substatement

rfc6087bis states in Section 4.11.3:

A separate description statement
   (within each 'enum' or 'bit' statement) SHOULD be present.

And it gives the following as an example, which gives me reason to believe that ietf-netconf-nmda SHOULD address the warning message. Do we agree?

       leaf foo {
         // INCORRECT
         type enumeration {
           enum one;
           enum two;
         }
         description
           "The foo enum...
            one: The first enum
            two: The second enum";
       }

       leaf foo {
         // CORRECT
         type enumeration {
           enum one {
             description "The first enum";
           }
           enum two {
             description "The second enum";
           }
         }
         description
           "The foo enum...  ";
       }

> On May 21, 2018, at 12:51 PM, Andy Bierman <[email-masked]> wrote:
> 
> 
> 
> On Mon, May 21, 2018 at 12:49 PM, Benoit Claise <[email-masked] <mailto:[email-masked]>> wrote:
>> My understanding is that SHOULD means you need a good reason not to follow the guideline.
> That's my understanding as well. At least this is the intent behind a SHOULD in a BCP.
> 
> 
>  
> 
> 3 <https://tools.ietf.org/html/rfc2119#section-3>. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
>> On Mon, May 21, 2018 at 12:27 PM, Mahesh Jethanandani <[email-masked] <mailto:[email-masked]>> wrote:
>> > On May 21, 2018, at 9:14 AM, Martin Bjorklund <[email-masked] <mailto:[email-masked]>> wrote:
>> > 
>> >>> https://www.ietf.org/mailman/listinfo/yang-doctors <https://www.ietf.org/mailman/listinfo/yang-doctors>
>> >>> 
>> 
>> Mahesh Jethanandani
>> https://www.ietf.org/mailman/listinfo/yang-doctors <https://www.ietf.org/mailman/listinfo/yang-doctors>
> 
> 

Mahesh Jethanandani
[email-masked]

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 22 May 2018 08:01:28 +0200

https://github.com/netconf-wg/netconf-nmda/commit/6eff92ea6b2e1aa3cf8ad89cf9820dd17ff10822

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 22 May 2018 08:23:25 +0200 (CEST)

> https://github.com/netconf-wg/netconf-nmda/commit/6eff92ea6b2e1aa3cf8ad89cf9820dd17ff10822

Hmmm, I actually think that this just adds noise.  The value
"unbounded" is clearly already documented, so this new statement
doesn't add anything.

IMO the gist of the SHOULD is that all enums need to be documented,
and we prefer that all enums are documented separately, rather than
the old SMIv2-style of documenting all enums in one description.  For
example, we prefer:

        leaf association-type {
          type enumeration {
            enum server {
              description
                "Use client association mode.  This device
                 will not provide synchronization to the
                 configured NTP server.";
            }
            enum peer {
              description
                "Use symmetric active association mode.
                 This device may provide synchronization
                 to the configured NTP server.";
            }
            ...
          }
          default server;
          description
            "The desired association type for this NTP server.";
        }

over

        leaf association-type {
          type enumeration {
            enum server;
            enum peer;
            ...
          }
          default server;
          description
            "The desired association type for this NTP server.

             The different enums mean:

             'server': Use client association mode.  This device
                       will not provide synchronization to the
                       configured NTP server.
             'peer':   Use symmetric active association mode.
                       This device may provide synchronization
                       to the configured NTP server.
             ...
             ";
        }

But in the case of max-depth, the enumeration "unbounded" is better
described together with the rest of the value space:

          "For each node selected by the filter, this parameter
           selects how many conceptual sub-tree levels should be
           returned in the reply.  If the depth is 1, the reply
           includes just the selected nodes but no children.  If the
           depth is 'unbounded', all descendant nodes are included.";

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Tue, 22 May 2018 08:27:33 +0200

Martin,

I rather add a description instead of holding off this document and
starting a debate whether in this particular case a separate
description statement is needed or not. NMDA was a big project and now
we get stuck because of this?

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 22 May 2018 15:41:16 +0200 (CEST)

> we get stuck because of this?

Does anyone *not* accept the motivation for the current model?  If
noone objects to the current document, we can simply proceed the
publication process without delays.

(I'm a bit worried that if we simply treat this SHOULD as a MUST, it
will set a precedence, and we have to treat all SHOULDs as MUSTs in
the future.  That was not the intention of using SHOULD.)

/martin

---

From: Christian Hopps <[email-masked]>
Date: Tue, 22 May 2018 10:03:00 -0400

> the future.  That was not the intention of using SHOULD.)

You're suggesting simply don't use Juergen's "fix", and proceed with the warning?

I think it's fine either way, but that's because I don't think accepting the "fix" is going to set any precedent unless we say it does.

I agree with Juergen -- please do not hold this document up.

Thanks,
Chris.

---

From: Robert Wilton <[email-masked]>
Date: Tue, 22 May 2018 15:20:55 +0100

My preference is to put Juergen's fix in.  My rationale is that we don't 
really have a strong reason not to have a description here.  I.e. I 
think that it is reasonable to exclude enum descriptions in the 
particular case where including them would detract from the readability 
of the YANG module.

But I don't feel that strongly here, I would like this to just get 
published and be done.

Thanks,
Rob

On 22/05/2018 15:03, Christian Hopps wrote:
> I think it's fine either way, but that's because I don't think 
> accepting the "fix" is going to set any precedent unless we say it does.
>
>>> > > > It seems that we agree that even though rfc6087bis is a BCP, 
>>> that authors need a good reason not to fix warnings (SHOULD) in the 
>>> YANG model.
>>> > > >
>>> > > > The reason I asked the question in the first place is because 
>>> of draft-ietf-netconf-nmda-netconf, which currently has one warning 
>>> reported against the YANG model.
>>> > > >
>>> > > > [email-masked]:205: warning: RFC 6087: 
>>> 4.10,4.12: statement "enum" should have a "description" substatement
>>> > > >
>>> > > > And it gives the following as an example, which gives me 
>>> reason to believe that ietf-netconf-nmda SHOULD address the warning 
>>> message. Do we agree?
>>> > > >
>>> > > >        leaf foo {
>>> > > >          // INCORRECT
>>> > > >          type enumeration {
>>> > > >            enum one;
>>> > > >            enum two;
>>> > > >          }
>>> > > >          description
>>> > > >            "The foo enum...
>>> > > >             one: The first enum
>>> > > >             two: The second enum";
>>> > > >        }
>>> > > >
>>> > > >        leaf foo {
>>> > > >          // CORRECT
>>> > > >          type enumeration {
>>> > > >            enum one {
>>> > > > > On Mon, May 21, 2018 at 12:49 PM, Benoit Claise 
>>> <[email-masked] <mailto:[email-masked]>> wrote:
>>> > > > > 3 <https://tools.ietf.org/html/rfc2119#section-3>. SHOULD   
>>> This word, or the adjective "RECOMMENDED", mean that there
>>> > > > >> In summary, what I am gathering from this discussion is 
>>> that it is ok for us to publish an IETF draft that contains a 
>>> normative YANG module, and that YANG module have warnings (SHOULD) 
>>> reported by pyang or other tools. But if the same module has an 
>>> error (MUST) reported by the tools, the error has to be fixed.
>>> > > > >>
>>> > > > >> Thanks.
>>> > > > >>
>>> > > > >> > On May 21, 2018, at 9:14 AM, Martin Bjorklund 
>>> <[email-masked] <mailto:[email-masked]>> wrote:
>>> > > > >> >
>>> <mailto:[email-masked]>> wrote:
>>> > > > >> >>

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Tue, 22 May 2018 14:46:03 +0000

+1. I see no reason not to have a description in this case.

Regards,
Reshad.

On 2018-05-22, 10:21 AM, "yang-doctors on behalf of Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked] on behalf of [email-masked]> wrote:

    
    Thanks,
    Rob

---

From: Kent Watsen <[email-masked]>
Date: Tue, 22 May 2018 19:29:55 +0000

This case is especially interesting since rfc6087bis's example says "INCORRECT", which sounds like an error.  Perhaps the rfc6087bis (in AUTH48 now) could be tweaked: s/INCORRECT/NOT PREFERRED/?

I think the SHOULD is well intended.  For instance, imagine a YANG-driven UI that likes to provide per-enum pop-ups.  Yes, it (and the user) must still handle the case when there isn't one, but it seems like that should be a rarity.

/kw

===== original message =====

Regards,
Reshad.

    
    
    Thanks,
    Rob

    On 22/05/2018 15:03, Christian Hopps wrote:
    >>> https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_netconf-2Dnmda_commit_6eff92ea6b2e1aa3cf8ad89cf9820dd17ff10822&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=eumGIBsdX4Ct4I61-hckZkSHMjSeHeNTYo6ZPDb9o5I&e=
    >>> >
    >>> > > > > 3 <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc2119-23section-2D3&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=xAw_FBUqOq_6zMLLHhQ9XUf0eQEYdT9--2WDg3nXRZE&e=>. SHOULD   
    >>> > > > >> >>> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e= 
    >>> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=>
    >>> > > > >> >>>
    >>> > > > >>
    >>> > > > >> Mahesh Jethanandani
    >>> > > > >> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e= 
    >>> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=>
    >>> > > > >
    >>> > > > >
    >>> > > >
    >>> > > > Mahesh Jethanandani
    >>> > > > [email-masked]
    >>> > > >
    >>> > >
    >>> > > > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=
    >>> > >
    >>> > >
    >>> > > --
    >>> > > Fax:   +49 421 200 3103 <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=pq5Hf0m24aePjr6jBZ45Sn_7rRY2TzombLWvXTsgTxw&e=>
    >>> > >
    >>> > > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=
    >>> > >
    >>>
    >>> -- 
    >>> Fax:   +49 421 200 3103 <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=pq5Hf0m24aePjr6jBZ45Sn_7rRY2TzombLWvXTsgTxw&e=>
    >>>
    >>
    >> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=
    >
    > https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=
    > .
    >
    
    _______________________________________________
    yang-doctors mailing list
    [email-masked]
    https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=

_______________________________________________
yang-doctors mailing list
[email-masked]
https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_yang-2Ddoctors&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=MXurAiJTorMhtCubauP59TDRcjzKf9v4HjpHeMHXQG0&e=

---

From: Martin Bjorklund <[email-masked]>
Date: Sat, 26 May 2018 12:15:03 +0200 (CEST)

Hi,

I don't want to delay the document, so if a new version is needed in
order to proceed, let's publish a new version with Juergen's fix.

But IMO we're on the wrong track here.  We're now at a point where we
add stuff just to keep tools quiet.  It just adds noise.  The
additional description doesn't add any information to the module.  We
now have:

      leaf max-depth {
        type union {
          type uint16 {
            range "1..65535";
          }
          type enumeration {
            enum "unbounded" {
              description
                "All descendant nodes are included.";
            }
          }
        }

Rhetoric question: Why isn't there a description for the uint16 branch
in the union?

The whole point of having a SHOULD instead of MUST is that there are
cases where the rule/recommendation simply doesn't need to be
followed.  IMO this is a perfect example of when the description isn't
needed.  The WG has decided that description for an enum is a SHOULD,
not a MUST, so why do we not follow this guideline?

/martin

Kent Watsen <[email-masked]> wrote:
> This case is especially interesting since rfc6087bis's example says
> "INCORRECT", which sounds like an error.  Perhaps the rfc6087bis (in
> AUTH48 now) could be tweaked: s/INCORRECT/NOT PREFERRED/?
> 
> I think the SHOULD is well intended.  For instance, imagine a
> YANG-driven UI that likes to provide per-enum pop-ups.  Yes, it (and
> the user) must still handle the case when there isn't one, but it
> seems like that should be a rarity.
> 
> /kw
> 
> On 2018-05-22, 10:21 AM, "yang-doctors on behalf of Robert Wilton -X
> (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked] on
> behalf of [email-masked]> wrote:
> 
>     >>> > > > > 3
>     >>> > > > > <https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_rfc2119-23section-2D3&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=xAw_FBUqOq_6zMLLHhQ9XUf0eQEYdT9--2WDg3nXRZE&e=>. SHOULD
>     >>> > > Fax: +49 421 200 3103
>     >>> > > <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=pq5Hf0m24aePjr6jBZ45Sn_7rRY2TzombLWvXTsgTxw&e=>
>     >>> > >
>     >>> Fax: +49 421 200 3103
>     >>> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.jacobs-2Duniversity.de_&d=DwIGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=OtBL3nq6ap4F4zpzNrYVgG7CgcMa223E2otpymcTSjc&s=pq5Hf0m24aePjr6jBZ45Sn_7rRY2TzombLWvXTsgTxw&e=>
>     >>>
>     >>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 26 May 2018 12:59:40 +0200

> not a MUST, so why do we not follow this guideline?

  (i) Because people want a clean compile.
 (ii) Because people do not want to have to enter a discussion every
      time whether an exception to the SHOULD applies or not.
(iii) Because people do not want to hold off important technical work
      debating weeks whether a non-harmful redundant description should
      be added or not.

And at the end of the day, if the SHOULD forces some redundant
descriptions, then this is likely less harmful than missing
descriptions and overall the SHOULD does its job even if it is
interpreted effectively as a MUST unless you have lots of time and
energy for a lengthy debate.

/js

PS: Have you never made changes to C code to get a clean compile even
    if the change was not strictly needed?