Decide on a versioning schema

[Kircheneer]

Problem statement

If we follow the Nautobot versioning schema 1:1 then we cannot release fixed versions for a given Nautobot versions, that means if there is a problem with the oapi code generation in a given release the only thing we can do is delete the already released version, potentially breaking other peoples code. As far as I can see SemVer doesn't allow for any versioning in addition to major.minor.patch, build metadata has to be ignored for version precedence checking and we aren't dealing with pre-releases here.

Open points

• [x] Research how similar libraries solve this issue
• [x] Research whether the API spec even changes with patch releases, thereby maybe obviating the need for tightly coupled versioning

[chadell]

I personally like the idea of not having a specific versioning for this library, and match directly the Nautobot versioning. So, for the X.Y.Z Nautobot version, we will have a X.Y.Z go-nautobot versioning. Obviously, this leads to the challenge of keeping semantic versioning in this project, when it is directly taken from the reference project (Nautobot). So, if during the bindings generation project for a specific version A.B.C, there is some issue due the oapi generator, and the version is released, we could move this version A.B.C to A.B.C.beta0, and republish the new version fixed to A.B.C. Obviously, this is is not keeping the semantic versioning rules, but if it's well documented, could make the usage of this library simpler from the user perspective (with the matching with Nautobot). The other alternative, having a custom versioning for this library, could make this trivial, but will require some mapping to describe which Nautobot version is supported. (similar to what pynautobot does, but it is not autogenerated for each Nautobot version) looking forward to hearing your thoughts on this

[chadell]

thoughts? @jvanderaa @glennmatthews @bryanculver

[Kircheneer]

@jvanderaa proposed deviating from SemVer the following way:

First release of go-nautobot for Nautobot version x.y.z gets version x.y.z.0, if we do need to do changes after that we can call it x.y.z.1 and so on. We should evaluate if tools like poetry can work with this, but I assume they can.

[chadell]

First release of go-nautobot for Nautobot version x.y.z gets version x.y.z.0, if we do need to do changes after that we can call it x.y.z.1 and so on. We should evaluate if tools like poetry can work with this, but I assume they can.

I would like to get the "stable" release per version in the x.y.z, so if a patch is needed I would like to see the old tag renamed to x.y.z.0, and the new one use the x.y.z

[glennmatthews]

I'm -1 on renaming tags. It's a recipe for confusion -- "I have x.y.z installed and I'm seeing issue ABC." "Oh, that was fixed in x.y.z, you need to uninstall your x.y.z and reinstall x.y.z"??

[chadell]

if the package managers understand this four octet, so we could the "latest" of the x..y.z version it would be good, as you can ignore the latest one, and focus on the Nautobot version

[bryanculver]

I'm -1 on renaming tags. It's a recipe for confusion -- "I have x.y.z installed and I'm seeing issue ABC." "Oh, that was fixed in x.y.z, you need to uninstall your x.y.z and reinstall x.y.z"??

Agree x :100:

Also, the BNF grammar for SerVer does not include a fourth "octet" (not an octet because it's not an base10 representation of a byte): https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions

This (x.y.z.N) will cause weirdness with many package managers.

[chadell]

one nice idea, suggested by @whitej6 would be to only care about major.minor from Nautobot, so it leave the third octet as depended on this library. At the end, the API is generated with api_version only with the major.minor from the tag with the Nautobot major.minor.patch

Nautobot -> go-nautobot 1.4.0 -> 1.4.0 1.4.1 -> 1.4.1 (error found!) Manual trigger, 1.4.1 -> 1.4.2 1.4.2 -> 1.4.3 ...

[jvanderaa]

Any thoughts on the x.y.z.n?

[glennmatthews]

one nice idea, suggested by @whitej6 would be to only care about major.minor from Nautobot, so it leave the third octet as depended on this library. At the end, the API is generated with api_version only with the major.minor from the tag with the Nautobot major.minor.patch

I'm in favor of this, i.e. versioning as <nautobot major>.<nautobot minor>.<go-nautobot patch>

[whitej6]

My pushback is that x.y.z.n isn't needed mainly because core doesn't introduce changes to the API in patch versions.

[jvanderaa]

Agreed with what is stated there, especially as @glennmatthews has laid it out.

[chadell]

so, do we have consensus here?

[Kircheneer]

IMO yes

[jvanderaa]

IMO yes

Same

[chadell]

Addressed in #12