Reconsider versioning

[jcchavezs]

Current versioning is somehow misleading and specially in go provides an unfriendly experience.

There are a few challenges with the approach Y.m.d:

1. A year bump means a new major release which could perfectly be bugfix or security patch. This imposes unnecessary uncertainty as humans and bots will be reluctant to bump to a major on a bugfix.
2. A breaking change (if any) happening in the same year can't be in the same major which is non sense because in a API rewrite you are forced to create yet a new API.
3. Every new year you break the import path for no reason github.com/opslevel/opslevel-go/v2023 -> github.com/opslevel/opslevel-go/v2024 causing unnecessary code changes.

I think there are a couple of options here

1. Go back to 1.x and retract 2023 and 2024 version
2. Start with something like 3000 and do semver from there.
3. Keep it as it is and think of it when you need to introduce a breaking change in a major (with a probably bigger userbase)

[rocktavious]

Hey @jcchavezs - We have explicitly chosen to not use SemVer due to the nature of not all breaking changes come in the form of an opslevel-go change due to its nature of being integrated with a living API of a SAAS product that gets changes deployed to it 20+ times a day.

Every opslevel-go release you must read the release notes for breaking changes (and we try our best to put in the changelog about them) BUT even then you might encounter a problem if the API has changed slightly (for example most 2023 versions won't work with our API fully because the Groups feature was removed). We try our best as an organization to make things work backwards compatible but its just not 100% feasible to adhere to strict SemVer. This is why CalVer was selected to communicate this.

If you are having problem then we urge you to use one of our tools - CLI, Terraform or Kubectl - instead of integrating directly with opslevel-go. Additionally you don't need to update opslevel-go unless you want to bring on the new changes you can easily pin to version from 6 months ago if you really need.

Lastly on the every year you break the import path - which this is true this is purely because of how golang works (which IMO is a terrible idea they put into package import statements - but we are where we are). That being said we've been doing this for 3 years now and we have several projects built ontop of opslevel-go where we have to do this - its trivial to do a code wide search and replace takes at most maybe 5 mins. IMO its a non issue.

[rocktavious]

Also as a whole the industry is leading towards SemVer being a terrible idea in the long run because it's almost impossible to predict what actually will be a breaking change - especially with APIs involved. Here are a bunch of articles that point out alot of this stuff.

Ultimately, SemVer is a false promise that appeals to many developers — the promise of pain-free, don't-have-to-think-about-it, updates to dependencies. But it simply isn't true. Node doesn't follow SemVer, Rails doesn't do it, Python doesn't do it, Ruby doesn't do it, jQuery doesn't (really) do it, even npm doesn't follow SemVer.

Major Version Numbers are not Sacred Poetry FAQ - Are unbound version constraints a bad idea? Should You Use Upper Bound Version Constraints? Why I Don't Like SemVer anymore

https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e <- this is really good breakdown too.

While i hear you on your concerns - i've put many years into thinking about this and have made this an explicit decision for the long term of opslevel's tools.

[jcchavezs]

@rocktavious thanks for the detailed explanation. Certainly I don't agree with most of the things mentioned here but I appreciate you put the effort to communicate this. I am closing the issue as no action will come out of it.