Re: [Netmod-ver-dt] [netmod-wg/yang-ver-dt] 1ad0ef: Numerous updates to the semver spec.

["Rob Wilton (rwilton)" <[e-mail]>]

Hi Joe,

I think that this draft is looking in pretty good shape!

I have a few comments, but mostly I think that they are all pretty minor.

1. You should be marked as the editor.

2. Section 1:
Introduction, perhaps change to (since the module-versioning draft only talks about modules):

  <t><xref target="I-D.verdt-netmod-yang-module-versioning"/> puts forth a number of concepts relating
   to modified rules for updating modules, a means to signal when a new revision of a module has
   non-backwards-compatible (NBC) changes compared to its previous revision, and a versioning scheme that
   uses the revision history as a lineage for determining from where a specific revision of a YANG
   module is derived.  Additionally, section 3.3 of <xref target="I-D.verdt-netmod-yang-module-versioning"/>
   defines a revision label which can be used as an overlay or alias to provide additional context or an additional
   way to refer to a specific revision.</t>

   This document defines a labeling scheme that uses modified [semver]
   rules for YANG artifacts (i.e. YANG modules and YANG packages (XXX, ref))
   as well as the revision label definition for using this scheme.
   The label and rules defined herein represent the
   RECOMMENDED revision label scheme to use for versioning IETF YANG artifacts.


3. XXX, I think that the last sentence of the intro means that this document should update YANG Author Guidelines, which should be explicitly stated.


4. Section 3.1, second to last paragraph.
  Vanilla semver (i.e. semver.org version 2.0.0) should also be allowed.  I don't know if this needs to be explicitly stated, of it is just obvious.  Or, do we require that if the version number looks like semver then everyone is required to support the m/M markers?

5. Section 3.2 title "Artifacts => YANG Artifacts"?

6. Section 3.2, third paragraph:

      Unlike the semver.org 2.0.0 versioning scheme, the YANG semantic
      versioning scheme supports limited updates to older versions of
      YANG artifacts, to allow for bug fixes and enhancements to
      artifact versions that are not the latest.  However, it does not
      provide for the unlimited branching and updating of older
      revisions which are provided by the general rules in
      [I-D.verdt-netmod-yang-module-versioning].

 I'm not sure that we should say "provided by", or perhaps better "allowed" or "facilitated", to indicate that it is allowed but not encouraged.


7. Perhaps somewhere early in the document, we want to say that [semver] means the semver 2.0.0 scheme, and then perhaps through the rest of the document, it doesn't need to keep repeating it?

8. Section 3.2, para 8:

   YANG packages that make use of this semantic versioning scheme will
   have their sematic version as the value of the "revision_label"
   property.

I'm not sure whether or not this should be stated in this draft, or just left to the packages draft?  Currently, I've changed the name of this leaf in the packaging draft to "version".

9. Section 3.2
I-D.verdt-netmod-yang-module-versioning does not define "editorial change" on BC and NBC, because the concept of an editorial change for a YANG module is really tied to a semver interpretation.  Hence, I think that this draft probably needs to be define an editorial change is in the context of a YANG module.  Perhaps take the definition from one of the older revisions of the draft as a starting point?

10. Section 3.2.1, last paragraph

   Looking at the version number alone, the module definition in 2.0.0
   does not necessarily contain the contents of 1.3.0.  However, the
   module revision history in 2.0.0 would likely indicate that it was
   edited from module version 1.3.0.

   Probably should change "would likely" to "may well".  Or alternatively, perhaps explain in a bit more detail that despite the relationship of semantic version numbers, the revision history illustrates what the actual base module was that 2.0.0 was created from.  It might be 1.3.0, but it could have been another version depending on when the versions were created.

11. Section 3.4.2
I think that the packaging example is good, but we'll need to remember to update it depending on what shape the packaging draft ends up in.  For the moment, perhaps just change "revision_label" to version.

Thanks,
Rob


From: Netmod-ver-dt <[e-mail]> On Behalf Of Joe Clarke (jclarke)
Sent: 06 September 2019 19:03
To: Joe Clarke <[e-mail]>
Cc: [e-mail]
Subject: Re: [Netmod-ver-dt] [netmod-wg/yang-ver-dt] 1ad0ef: Numerous updates to the semver spec.

I pushed my changes.  The diff can be viewed at:

https://tools.ietf.org/rfcdiff?url1=https://raw.githubusercontent.com/netmod-wg/yang-ver-dt/0d25a6db1e58f062d02ab3636e58ffe571b3ecfa/yang-semver/draft-verdt-netmod-yang-semver.txt&url2=https://raw.githubusercontent.com/netmod-wg/yang-ver-dt/develop/yang-semver/draft-verdt-netmod-yang-semver.txt

Joe


On Sep 6, 2019, at 13:56, Joe Clarke <[e-mail]<mailto:[e-mail]>> wrote:

 Branch: refs/heads/develop
 Home:   https://github.com/netmod-wg/yang-ver-dt
 Commit: 1ad0ef542c17d3ae1dadae9ea54c7c74b9d2ef59
     https://github.com/netmod-wg/yang-ver-dt/commit/1ad0ef542c17d3ae1dadae9ea54c7c74b9d2ef59
 Author: Joe Clarke <[e-mail]<mailto:[e-mail]>>
 Date:   2019-09-06 (Fri, 06 Sep 2019)

 Changed paths:
   M yang-semver/draft-verdt-netmod-yang-semver.txt
   M yang-semver/draft-verdt-netmod-yang-semver.xml
   A yang-semver/ietf-yang-semver.yang

 Log Message:
 -----------
 Numerous updates to the semver spec.

* Genericize the wording using the term "artifact" so that semver can be
applied to YANG packages as well as modules.

* Add language that says anything that looks like a semver is a semver
and must adhere to these rules.

* Add a YANG module that specifies a semver typedef.


_______________________________________________
Netmod-ver-dt mailing list
[e-mail]<mailto:[e-mail]>
https://www.ietf.org/mailman/listinfo/netmod-ver-dt