Subject: [netmod] module-versioning should require any solution to describe labels for drafts

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 22 Jun 2020 15:24:33 +0000

Hi guys,

In the latest working copy of the YANG Semver draft we added some text in section 5 about how to select revision labels for modules that are under development, or for RFCs that are churning (i.e. bis versions).

https://github.com/netmod-wg/yang-ver-dt/blob/master/yang-semver/draft-ietf-netmod-yang-semver.txt

I think we probably need to require that same information for any revision label scheme. I'd suggest we put something along these lines into the module-versioning draft:

Any revision label scheme MUST describe how labels are selected for new YANG modules that are under development, and how labels are selected for modules in IETF RFCs that are being updated (e.g. a "bis" version is under development).

(should we drop the "in IETF RFCs" ? )

Jason

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 22 Jun 2020 17:41:28 +0200

I have RFCXXXX at version 1.0.0. I make some backwards compatible
changes. I then make a backwards incompatible change. Then I add more
backwards compatible changes. Then I remove the backwards incompatible
change. What are the resulting version numbers?

Rhetoric question: How many IETF module authors will get this all done
correctly during module revision (and which problem does all of this
fix)?

/js

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

-- 
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: "Joe Clarke (jclarke)" <[email-masked]>
Date: Mon, 22 Jun 2020 15:56:56 +0000

> On Jun 22, 2020, at 11:41, Juergen Schoenwaelder <[email-masked]> wrote:
> 

If this is done in development, your version may look like 2.0.0-RFCXXXXbis-dev1 or 1.1.0-RFCXXXXbis-dev5 (depending on what your final intent is).  For in-development work, the only things the new text mandates are using the ‘-‘ pre-release notation and making sure any released module (i.e., one that appears in a rev of the I-D in Data Tracker) has a unique version number across its entire lifetime.  The rules of MAJOR.MINOR.PATCH do not strictly apply here since this is pre-release work.

> correctly during module revision (and which problem does all of this

The reason for the unique version even for development is so someone implementing or using this module knows exactly which module and version has been implemented.

Joe

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 22 Jun 2020 16:01:59 +0000

Hi Juergen,

Section 5 in the link below attempts to explain how to manage this (but always happy for review of that text to help improve it).

The key is to always ensure there is a unique version for every revision that exists.

In your example below it would go like this:

I have RFCXXXX at version 1.0.0. I make some backwards compatible changes:
1.0.0

I then make a backwards incompatible change:
1.1.0-XXXXbis-dev1

Then I add more backwards compatible changes:
2.0.0-XXXXbis-dev2

Then I remove the backwards incompatible change:
1.1.0-XXXXbis-dev3

When the module is finally published as an RFC it would just be version 1.1.0 in this case.

The main problems covered:
- ensure all intermediate versions have a unique identifier (in case there are pre-release implementations, etc)
- ensure the final version has the correct YANG Semver

Jason

> -----Original Message-----
> From: Juergen Schoenwaelder <[email-masked]>
> Sent: Monday, June 22, 2020 11:41 AM
> To: Sterne, Jason (Nokia - CA/Ottawa) <[email-masked]>
> Cc: [email-masked]
> Subject: Re: [netmod] module-versioning should require any solution to describe
> labels for drafts
> 
> > In the latest working copy of the YANG Semver draft we added some text in
> section 5 about how to select revision labels for modules that are under
> development, or for RFCs that are churning (i.e. bis versions).
> >
> > I think we probably need to require that same information for any revision
> label scheme. I'd suggest we put something along these lines into the module-
> versioning draft:
> >
> > Any revision label scheme MUST describe how labels are selected for new
> YANG modules that are under development, and how labels are selected for
> modules in IETF RFCs that are being updated (e.g. a "bis" version is under
> development).
> >

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 22 Jun 2020 18:29:45 +0200

> I have RFCXXXX at version 1.0.0. I make some backwards compatible changes:

I use the same version number until I make an incompatible change?

/js

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Mon, 22 Jun 2020 16:39:04 +0000

Sorry - I messed that up with my copy-n-pasting and editing.  Let me try that again 😊

I have RFCXXXX at version 1.0.0.
1.0.0

 I make some backwards compatible changes. 
1.1.0-XXXXbis-dev1

I then make a backwards incompatible change. 
2.0.0-XXXXbis-dev2

Then I add more backwards compatible changes. 
2.0.0-XXXXbis-dev3

Then I remove the backwards incompatible change. 
1.1.0-XXXXbis-dev4

Then if we published the RFC at that point it would be 1.1.0

Jason

> Sent: Monday, June 22, 2020 12:30 PM
> > Section 5 in the link below attempts to explain how to manage this (but always
> happy for review of that text to help improve it).
> >

---

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Fri, 26 Jun 2020 19:10:39 +0000

Hi all,

In our weekly call this week we debated the format of the yang semver for updates & new modules.

We found a corner case in the proposal below and would suggest a slight modification: 
- include either the authors name (for non-adopted drafts) or the word 'ietf' for adopted drafts, and
- use the draft # as a suffix.  For example:
    1.1.0-smith-XXXXbis-03

So the general scheme is:
    A.B.C-<author name or 'ietf'>-XXXXbis-yy
where:
    A.B.C = the current estimated final SemVer digits for the new RFC
    <author name or 'ietf'> = before a draft is adopted it has a name like draft-smith-foo-03 and after it is adopted it becomes draft-ietf-netmod-foo-00.  Pre-adoption use 'smith' in the revision-label and post-adoption use 'ietf'.
    XXXX = the RFC being updated
    yy = the draft version number

Another alternative we came up with that is simple and avoids all potential collisions is this:
    A.B.C-<full draft name>
For example: 
    1.1.0-draft-smith-foo-03

It will make for long revision-labels and more importantly long file names, but it is very simple and easy to follow.

Our inclination at the moment is to prescribe the A.B.C part and then say that all draft and published versions must have a unique revision-label.  Then provide those two methods as example of how to achieve unique labels.

Jason

> From: Sterne, Jason (Nokia - CA/Ottawa)
> Sent: Monday, June 22, 2020 12:39 PM
> To: Juergen Schoenwaelder <[email-masked]>
> Cc: [email-masked]
> Subject: RE: [netmod] module-versioning should require any solution to
> describe labels for drafts
> 
> > On Mon, Jun 22, 2020 at 04:01:59PM +0000, Sterne, Jason (Nokia -
> CA/Ottawa)
> > wrote:
> > > Hi Juergen,
> > >
> changes:
> > > When the module is finally published as an RFC it would just be version
> 1.1.0 in
> > this case.
> > >