Subject: Re: [netmod] FW: revision in YANG RFCs

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 24 Sep 2010 09:32:54 +0200

Hi,

I am CCing the NETMOD working group since this should not be a private
discussion.

On Thu, Sep 23, 2010 at 09:50:58PM +0200, Mark Scott wrote:
> I got a delivery failure so resending this.
> 
> -----Original Message-----
> From: 
> Sent: September-23-10 3:24 PM
> To: 'Juergen Schoenwaelder'
> Cc: Martin Bjorklund
> Subject: RE: revision in YANG RFCs
> 
> Juergen,
> 
> From sec 4.7:
> 
> "Each new revision MUST include a revision date which is higher than
>    any other revision date in the module.  The revision date does not
>    need to be updated if the module contents do not change in the new
>    document revision.
> 
>    It is acceptable to reuse the same revision statement within
>    unpublished versions (i.e., Internet-Drafts), but the revision date
>    MUST be updated to a higher value each time the Internet-Draft is re-
>    published."
> 
> It's the second paragraph which I interpret as meaning that all
> modules must have their revision date changed if the RFC containing
> them is republished, overriding the first paragraph.
> 
> I agree the probability is low for RFCs which contain little more
> than a single module, but for cases where a RFC contains multiple
> modules this forces an unneeded revision.

Again, as far as I know, this never happened with MIB modules so
far. I am more concerned about the wording I guess since I am not sure
what "Internet-Draft is republished" really means. Perhaps the second
paragraph should read:

   It is acceptable to reuse the same revision statement within
   unpublished versions (i.e., Internet-Drafts), but the revision date
   MUST be updated to a higher value each time a modified module is
   re-published as an RFC.

> It could also become a nuisance for those who want to implement a
> module once it's been approved by the WG (which is arguably post
> WGLC) but before it's gone through the RFC editorial process.  This
> can be mitigated by suggesting that the last 'agreed' revision
> (ie. as found in the last draft at WGLC) is preserved at RFC
> publication time.

Here is where I disagree. There is lots of stuff happening after WGLC
and the publication really happens once the RFC pops up. 

> Though this doesn't align with what Bert was suggesting - which is
> to up-version the module to match the RFC publication date - unless
> I misinterpreted that.

I think Bert's suggestion is fine. There are editorial changes carried
out by the RFC editor in every module before it gets published.

/js

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

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 24 Sep 2010 09:49:24 +0200 (CEST)

Hi,

Juergen Schoenwaelder <[email-masked]> wrote:
> what "Internet-Draft is republished" really means.

The intention is that you do not have to keep old revision statements
when you issue a new version of an I-D.  You can essentially have:

  revision 2010-04-01 {
    description "Inital revision";
  }

and just update the date everytime you issue a new version of the
I-D.

The text says that this is ok, but you MUST remember to update the
date.

"re-publish" is not a good term for I-Ds, since I-Ds by definition are
"unpublished".  Is "issued" better?  Maybe the text could be:

    It is acceptable to reuse the same revision statement within
    unpublished versions (i.e., Internet-Drafts), but the revision
    date MUST be updated to a higher value each time a new version of
    Internet-Draft is issued with a modified module.

> and the publication really happens once the RFC pops up. 

+1

> out by the RFC editor in every module before it gets published.

+1.  Should we document this suggestion (which was that the revision
date must be updated by the rfc-editor when the rfc is published)
somewhere?

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 24 Sep 2010 10:17:09 +0200

>     Internet-Draft is issued with a modified module.

Oh, this is a completely different interpretation of the paragraph. So
obviously the paragraph needs improvement. Given your interpretation,
I am unsure what MUST really means - is the idea that an I-D will not
be posted if the author fails to comply to a MUST? We are not talking
about implementation requirements here. Seems to me like a wrong usage
of MUST.
 
> date must be updated by the rfc-editor when the rfc is published)

That might be good. Perhaps we should update the template module to
be more clear:

OLD:

    // replace '2010-05-18' with the module publication date
    // The format is (year-month-day)
    revision "2010-05-18" {
      description
        "Initial version";
    }

NEW:

    // RFC Ed.: replace '2010-05-18' with the module publication date
    // The format is (year-month-day)
    revision "2010-05-18" {
      description
        "Initial version";
    }

Since this document is in IESG Evaluation::AD Followup, I am not sure
what the changes are of getting any of these changes made.

/js

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 24 Sep 2010 10:22:46 +0200

> what the changes are of getting any of these changes made.

Looking at the template, it seems the reference statement above the
revision statement is misplaced as well.

OLD:

    // RFC Ed.: replace XXXX with actual RFC number and remove this note

    reference "RFC XXXX";

    // RFC Ed.: remove this note
    // Note: extracted from draft-ietf-netmod-yang-usage-04.txt

NEW:

    // RFC Ed.: replace '2010-05-18' with the module publication date
    //          (format is year-month-day) and remove this note
    revision "2010-05-18" {
      description
        "Initial version";
      // RFC Ed.: replace XXXX with actual RFC number and remove this note
      reference "RFC XXXX: <title>";
    }

At least that seems to be what we are using at the moment.

/js

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 24 Sep 2010 10:29:25 +0200 (CEST)

> about implementation requirements here. Seems to me like a wrong usage

I think this is intended as a (strong) guideline for I-D authors.  The
document also has this, for example:

   The following sections MUST be present in an Internet-Draft
   containing a module:

   o  Narrative sections

   o  Definitions section

   o  Security Considerations section

   o  IANA Considerations section

   o  References section

The same argument applies here - the I-D can still be posted if
Security Considerations is missing, of course.

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 24 Sep 2010 12:46:10 +0200 (CEST)

>       reference "RFC XXXX: <title>";

And we should also update the template with another RFC editor note:

OLD:

<CODE BEGINS> file "[email-masked]"

NEW:

// RFC Ed.: replace '2010-05-18' with the module publication date
//          (format is year-month-day) and remove this note
<CODE BEGINS> file "[email-masked]"

/martin

---

From: Mark Scott <[email-masked]>
Date: Fri, 24 Sep 2010 08:41:23 -0400

Hi,

If consensus is for a higher revision date each time a module is published (whether modified or not) then I'd suggest we remove any discretion and document type specific handling and simplify the guideline.

How about:

Sec 4.7 CURRENT:
  Each new revision MUST include a revision date which is higher than
  any other revision date in the module.  The revision date does not
  need to be updated if the module contents do not change in the new
  document revision.

  published.

Sec 4.7 PROPOSED:
  Each module revision date MUST be updated to a higher value every time the     
  module is published.  The revision date SHOULD be the date of publication
  of the document (e.g. I-D or RFC) containing the module.

Mark

-----Original Message-----
From: Martin Bjorklund [mailto:[email-masked]] 
Sent: September-24-10 3:49 AM
To: [email-masked]
Cc: Mark Scott; [email-masked]
Subject: Re: revision in YANG RFCs

Hi,

  revision 2010-04-01 {

+1

/martin

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 24 Sep 2010 15:54:15 +0200

On Fri, Sep 24, 2010 at 02:41:23PM +0200, Mark Scott wrote:
 
> If consensus is for a higher revision date each time a module is
> published (whether modified or not) then I'd suggest we remove any
> discretion and document type specific handling and simplify the
> guideline.

I think the other interpretation of the text where "Internet-Draft is
re-published" means "Internet-Draft is posted" makes perfectly sense.

/js

---

From: Andy Bierman <[email-masked]>
Date: Fri, 24 Sep 2010 09:35:17 -0700

Hi,

We need to nail down this detail.
It keeps coming up in vendor modules as well.
I object to the changes below because it goes against years
of best current practice.

If nothing changes within the module contents, the author does not need
to bump the revision date.  This happens a lot in I-Ds, especially since
the I-D boilerplate changes so often.

Some people don't even want to bump the revision date unless there is
some visible change (either on the wire or to an implementor).

For example, if I change "e.g." to "e.g.," and just add a comma,
and no semantics changed, and no syntax changed, does it really
help the NMS developer or operator to introduce a new module version?
We make editorial changes like this many times during the I-D lifetime.

Since this is a slippery slope, it is best to say that any change whatsoever
to the module contents (even adding 1 comma), counts as a change and therefore
the revision-stmt needs to be updated.  (I think this is the current guideline.)

Andy

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Mark Scott
Sent: Friday, September 24, 2010 5:41 AM
To: Martin Bjorklund; [email-masked]
Cc: [email-masked]
Subject: Re: [netmod] revision in YANG RFCs

Hi,

How about:

Sec 4.7 CURRENT:

Sec 4.7 PROPOSED:

Mark

-----Original Message-----
From: Martin Bjorklund [mailto:[email-masked]] 
Sent: September-24-10 3:49 AM
To: [email-masked]
Cc: Mark Scott; [email-masked]
Subject: Re: revision in YANG RFCs

Hi,

  revision 2010-04-01 {

+1

/martin
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Andy Bierman <[email-masked]>
Date: Fri, 24 Sep 2010 22:47:40 -0700

On 09/24/2010 01:29 AM, Martin Bjorklund wrote:
.....
>>>     Internet-Draft is issued with a modified module.

usage-10, sec. 4.7, para 7: note sentence 2.

usage-10, sec. 4.7, para 8:

OLD:

NEW:

OK?

> Security Considerations is missing, of course.

I guess application of 2119 terms is kind of strange here.
They really only matter when the IETF (or YANG Doctors)
reviews a YANG module being published as an RFC.

You can expect a module with MUST violations to be returned for modification.
Run 'pyang --ietf' to make sure the module will pass basic inspection.

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sat, 25 Sep 2010 11:23:59 +0200

>   Internet-Draft is issued with a modified module.

Yes, much better.

/js

---

From: Phil Shafer <[email-masked]>
Date: Sat, 25 Sep 2010 10:40:48 -0400

s/i.e./e.g./

("i.e. implies a complete list; e.g. lists examples)

Thanks,
 Phil

---

From: Andy Bierman <[email-masked]>
Date: Sat, 25 Sep 2010 10:04:37 -0700

> ("i.e. implies a complete list; e.g. lists examples)

I know the difference.  The i.e. was intentional because we keep insisting
that these guidelines only apply to IETF standards track modules.
Does e.g. make the guideline ambiguous?  Unclear?  IESG concerned?
If not, then this is fine with me.

Andy

---

From: Phil Shafer <[email-masked]>
Date: Sat, 25 Sep 2010 17:05:58 -0400

>that these guidelines only apply to IETF standards track modules.

Sorry, I lost the context.  If this is just in the usage doc, then
it's not a concern.

Thanks,
 Phil