Versioning proposal

[mraerino]

Currently we are not tagging this library in a way that is compatible with what go mod suggests. It would be good to use semver.

If we want to include the netbox version in the release tag, we could use the condensed form, like 27 for 2.7, because api breakage happens on minor, not patch versions

Proposal 1: break in 0.x

• always stay on 0.x
• upgrade minor with netbox (non-patch) versions
• semver allows breaking changes in minor version when on 0.x

This would mean we'd have versions like 0.27.1 for the second patch release supporting netbox 2.7.

Proposal 2: breaking per go spec

• add major packages like v27 as subdirectories
• pro: we'd have a client for every netbox version
• pro: allows larger changes inside the library, e.g. v27.2.0
• con: a lot of subdirs potentially

This would mean people needed to use the library in this way: github.com/netbox-community/go-netbox/v27

---

In both cases it would still be possible to version changes in the library via increasing the patch number. But any breaking changes would need to be synchronized with netbox releases.

[smutel]

We definitively need a real versioning on this project. +1 for the proposal 2 but not with sub-folders but with branches and tags For example: branch v27.x.x, v28.x.x and tags v27.1.0, v28.1.1, etc ...

[kobayashi]

Thanks @mraerino, I agree option2!

[jeremy-albinet]

:+1: for @smutel proposal that I tried to reword as:

Proposal 3: Use netbox version for major and minor

• eg: tags 2.9.x, 2.7.x where x is just our releases ; one branch per version we want to maintain
• pro: respect go specs and go modules (no sub-folder)
• pro: we'd have a client for every netbox version we want to maintain
• cons: maybe breaks semver (not really because we follow Netbox)
• cons: could be misleading to have a Netbox 2.9.12 but only go-netbox 2.9.2

Note: I'm in favor of 2.9.x instead of 29.x.x because I think we don't need minors, we are only doing patches to fix swagger original json no? But we can keep this proposal and use 29.x.x for tags and branches to have minor and patch releases.

[Comradin]

What is the stand here? We successfully shot ourself in the feet with the broken version.

[v0ctor]

The project now follows Semantic Versioning standard so as not to reinvent the wheel. 🤓