Subject: Re: [Netmod-ver-dt] solution proposal for YANG versioning: stream + SemVer

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 19 Jul 2018 12:46:47 +0000

Adding Ebben and Michael and the alias.

From: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
Date: Thursday, July 19, 2018 at 8:38 AM
To: "Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked]>, Balazs Lengyel <[email-masked]>, "Benoit Claise (bclaise)" <[email-masked]>, "Joe Clarke (jclarke)" <[email-masked]>, Juergen Schoenwaelder <[email-masked]>, Mahesh Jethanandani <[email-masked]>, Qin Wu <[email-masked]>, "Reshad Rahman (rrahman)" <[email-masked]>
Subject: solution proposal for YANG versioning: stream + SemVer

Hello YANG versioning design team,

Please add in Ebben Aries and Michael (Wangzitao).  I couldn't find an email address for them.

I had some hallway conversations with Rob Wilton and Benoit Claise this week that has led to this solution proposal for YANG versioning.

One key point for me is requirement 4.4.  There is a need to support multiple long-lived parallel streams of the same YANG module (e.g. multiple product releases), and there could even be a non-backwards-compatible change within one of those multiple streams.

Here is a figure to illustrate the issue and proposed solution (also enclosed as a text doc). This is not a full blown solution to all problems in the doc, and needs further refinement, but is hopefully a potentially useful approach to discuss.

The basic idea is to:

1. use SemVer *within* a stream

2. SemVer only has scope within a single stream

3. each stream has an independent contiguous set of module versions which are independent from any other stream

4. within each stream, non-backwards-compatible changes are only done to the *latest* version (note that we *could* decide to be more strict and say that *all* changes within a stream must occur to the latest version).

This allows the possibility of a major change within a stream (which should be unusual, but we should be able to handle this possibility).

Notice below that I reset SemVer to 1.0.0 for each new stream.  I don't think we can make SemVer span multiple streams because of version C below (what would the SemVer be for A, R, Y and C in that case ??).

Module: my-bgp

Rel 6

+---------------+-----------#---------+------------+---

A               B\          C         D            E

                  \

                   \ Rel 7

                    +-----------+-----+--------+------

                    R           S\    T        U

                                  \

                                   \ Rel 8

                                    #----------

                                    Y

---date---->

A-Z are labels for various versions of the my-bgp module.

Versions D & T are on the same date, but contain different changes.

Rel 6, 7, 8 are 3 independent streams.

+ = backwards compatible change

# = non-backwards compatible change

Module versions are labelled with:

- Stream identifier (unique string ?)

- SemVer

- Revision (necessary ?)

A: Stream = 6, SemVer = 1.0.0, Revision = 2018-07-01

B: Stream = 6, SemVer = 1.1.0, Revision =

C: Stream = 6, SemVer = 2.0.0, Revision =

D: Stream = 6, SemVer = 2.1.0, Revision = 2019-10-10

E: Stream = 6, SemVer = 2.2.0, Revision =

R: Stream = 7, SemVer = 1.0.0, Revision =

S: Stream = 7, SemVer = 1.1.0, Revision =

T: Stream = 7, SemVer = 1.2.0, Revision = 2019-10-10

U: Stream = 7, SemVer = 1.3.0, Revision =

Y: Stream = 8, SemVer = 1.0.0, Revision =

Another thing to consider is what filenames to use for A-Z.  Perhaps something like this ?

     <module-name>@<stream>-<semver>-<revision>.yang

     e.g. T: [email-masked]<mailto:[email-masked]>

That would allow all versions of the module to be placed into the same file directory.

Regards,

Jason

---

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thu, 19 Jul 2018 12:51:53 +0000

I think not being to use semver across streams is shared by a few people.

Adding Chris to get his take from the client side.

From: "Reshad Rahman (rrahman)" <[email-masked]>
Date: Thursday, July 19, 2018 at 8:46 AM
To: "Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>, "Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)" <[email-masked]>, Balazs Lengyel <[email-masked]>, "Benoit Claise (bclaise)" <[email-masked]>, "Joe Clarke (jclarke)" <[email-masked]>, Juergen Schoenwaelder <[email-masked]>, Mahesh Jethanandani <[email-masked]>, Qin Wu <[email-masked]>, Ebben Aries <[email-masked]>, wangzitao <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: Re: solution proposal for YANG versioning: stream + SemVer

The basic idea is to:

Module: my-bgp

Rel 6

A               B\          C         D            E

                  \

                   \ Rel 7

                    R           S\    T        U

                                  \

                                   \ Rel 8

                                    #----------

                                    Y

---date---->

- SemVer

- Revision (necessary ?)

Regards,

Jason

---

From: Joe Clarke <[email-masked]>
Date: Thu, 19 Jul 2018 09:00:00 -0400

> I think not being to use semver across streams is shared by a few people.

I had thought about this: add another number (in essence).  I didn't
call it a stream, but tied it to like a branch version.

This works, but I kept getting caught up with import-by-version.  That
gets messy.

It may not be as messy if you can't import outside of your stream (in
Jason's parlance).  The end users would then need to keep multiple
versions of a module (per stream) even if they happen to be compatible
across streams.  This, however, may not be such a bad thing.

As Jason says, this makes it easy to compartmentalize modules.

In terms of naming and revision, for now (YANG 1.1) we definitely need
to keep revision (at least within the module).  The name of the module
should likely be different (open question in clacla).  This is rather
minor in the grand scheme of things, but maybe:

[email-masked]

Joe

> *From: *"Reshad Rahman (rrahman)" <[email-masked]>
> *Date: *Thursday, July 19, 2018 at 8:46 AM
> *To: *"Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>,
> "Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)"
> <[email-masked]>, Balazs Lengyel <[email-masked]>,
> "Benoit Claise (bclaise)" <[email-masked]>, "Joe Clarke (jclarke)"
> <[email-masked]>, Juergen Schoenwaelder
> <[email-masked]>, Mahesh Jethanandani
> <[email-masked]>, Qin Wu <[email-masked]>, Ebben Aries
> <[email-masked]>, wangzitao <[email-masked]>
> *Cc: *"[email-masked]" <[email-masked]>
> *Subject: *Re: solution proposal for YANG versioning: stream + SemVer
> 
>  
> 
> *From: *"Sterne, Jason (Nokia - CA/Ottawa)" <[email-masked]>
> *Date: *Thursday, July 19, 2018 at 8:38 AM
> *To: *"Robert Wilton -X (rwilton - ENSOFT LIMITED at Cisco)"
> <[email-masked]>, Balazs Lengyel <[email-masked]>,
> "Benoit Claise (bclaise)" <[email-masked]>, "Joe Clarke (jclarke)"
> <[email-masked]>, Juergen Schoenwaelder
> <[email-masked]>, Mahesh Jethanandani
> <[email-masked]>, Qin Wu <[email-masked]>, "Reshad Rahman
> (rrahman)" <[email-masked]>
> *Subject: *solution proposal for YANG versioning: stream + SemVer
> 
>  
> 
> I had some hallway conversations with Rob Wilton and Benoit Claise this
> week that has led to this solution proposal for YANG versioning. 
> 
>  
> 
> One key point for me is requirement 4.4.  There is a need to support
> multiple long-lived parallel streams of the same YANG module (e.g.
> multiple product releases), and there could even be a
> non-backwards-compatible change within one of those multiple streams.
> 
>  
> 
> Here is a figure to illustrate the issue and proposed solution (also
> enclosed as a text doc). This is not a full blown solution to all
> problems in the doc, and needs further refinement, but is hopefully a
> potentially useful approach to discuss.
> 
>  
> 
> The basic idea is to:
> 
> 1. use SemVer **within** a stream
> 
> 3. each stream has an independent contiguous set of module versions
> which are independent from any other stream
> 
> 4. within each stream, non-backwards-compatible changes are only done to
> the **latest** version (note that we **could** decide to be more strict
> and say that **all** changes within a stream must occur to the latest
> version).
> 
>  
> 
> This allows the possibility of a major change within a stream (which
> should be unusual, but we should be able to handle this possibility).
> 
>  
> 
> Notice below that I reset SemVer to 1.0.0 for each new stream.  I don't
> think we can make SemVer span multiple streams because of version C
> below (what would the SemVer be for A, R, Y and C in that case ??).
> 
>  
> 
> Module: my-bgp
> 
> Rel 6
> 
>      e.g. T:
> [email-masked]<mailto:[email-masked]>
>

---

From: Balazs Lengyel <[email-masked]>
Date: Thu, 19 Jul 2018 09:37:55 -0400

File naming is a secondary issue. As most (but not all) our modules are 
kept in git, changing the name of the module by adding date/version is 
usually not done.  It must be optional.

If B and R are compatible, I would not like to loose that information 
even if they are on different tracks.

While some people may need this complicated multitrack versioning, many 
others including IETF will not need it.   Some of the changes in 
different tracks can be hidden by adding them but "removing" them with 
if-feature.

regards Balazs

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
Senior Specialist
Mobile: +36-70-330-7909              email: [email-masked]