Consistent Specification Versioning in OpenConfig

[wenovus]

Question: How should we version specifications and service definitions such that their relationship is clear? (i.e. we can find a one-to-one or one-to-most-recent mapping)

Background thread comment describing the issue and containing a proposal

It's good that this sparked off great conversation but we may want to move this thread (or at least back ref it) somewhere else otherwise we are going to have a very hard time finding this history at a later date.

+1 for @wenovus comment above as I think we just need to draw a relationship between the specification and IDL. The specification is filling in behavioral gaps over time that don't necessarily change message structs or service RPCs

But I'd also like to call this out for all projects that fall under the OpenConfig umbrella and we should drive this consistent approach across all. To date, this should apply to:

• All specifications and relevant model/API definitions must have explicit versioning
• All specifications and relevant model/API definitions must carry a changelog outside of commit messages
• Where specifications are detached from an underlying model/API, a relationship must exist
• Where there is some specification (or behavior guidance) directly in the model/API definition, consider detaching into a formal specification otherwise we run the risk of version increments in the model/API definition for doc changes
• Consideration of maintaining old versions of model/API definitions and surrounding specifications vs. overwriting files in a single location. It is quite often one needs to refer to old versions, be able to fetch them, compare, etc.. and we are currently left to sifting through commits, hashes (since we also do not have official releases or tags) in order to retrieve these versions - essentially its a guessing game based off commit descriptions and timestamps to locate.

Across the various repos (gribi, gnoi, grpctunnel, public, gnmi, etc..) - we have various inconsistencies of above

I'm curious whether gnmi.proto should be at v1.0.0 since it looks like users are depending more and more on the API and we're starting to worry about backwards compatibility (e.g. the recent double change in gnmi.proto)?

The blunt reality is version scheme aside, dependencies have been created since ~0.4.0 of the IDL due to this shipping in mainline code in various implementations so the worry has always been there

As far as bumping to 1.0.0, I know at least there are a handful of considerations (and some deprecation of fields that were never implemented/used) that should probably get addressed before we bump to a major version that indicates greater stability. Some of these currently sit as idle or unaddressed PRs/issues in the gNMI repo.

Originally posted by @earies in #175 (comment)