Skip to content
This repository has been archived by the owner on Oct 20, 2023. It is now read-only.

versioning the spec #68

Closed
michelleN opened this issue Sep 25, 2019 · 5 comments · Fixed by #81
Closed

versioning the spec #68

michelleN opened this issue Sep 25, 2019 · 5 comments · Fixed by #81

Comments

@michelleN
Copy link
Contributor

Does anyone have any thoughts on versioning the spec? I think we should consider versioning each part of the spec (each API) described in the spec independently. For example, traffic split may be pretty stable at this point and ready to move on to whatever version signals stability but traffic access may still have some work. If each API is able to signal it's ready to graduate to the next marker of stability, it would give us all a better idea of where we are in terms of each part of the spec.

If this were a regular go project like the go sdk, I would recommend, we version everything at v0.1.0 (referring to it as alpha maturity) until we reach the point of wanting to cut a v1.0.0-beta and then graduate to v1.0.0 like we're doing with the smi-sdk-go project. However, CNAB called its pre-1.0.0 version of the spec a Working Draft until it was ready and that's also a pretty common way to describe the state of a spec.

prior art:

@grampelberg
Copy link
Collaborator

I don't have any real preference on the version numbering. I personally dislike semver and prefer time based versioning but that's a pretty minion opinion.

I'm a massive +1 to keeping each spec versioned separately, that's why the CRDs all have their own groups.

@michelleN
Copy link
Contributor Author

@grampelberg thanks. what do u mean by time based versioning?

@grampelberg
Copy link
Collaborator

Couple examples:

  • CoreOS - 2191.0.0 or number of days since the first release.
  • Linkerd - edge-19.9.5 or 5th release of september in 2019.

My primary reasoning is that if you use something semver like, people make assumptions about the guarantees and those assumptions are usually wrong. Picking a completely ridiculous date forces them to look at the changelog. I like using dates for this because it helps with debugging "oh, you're on that release from a year ago".

@leecalcote
Copy link
Member

In agreement with @grampelberg, I find that there's often a need for semver+. e.g. major.minor.patch+candidate/something else.

@rickducott
Copy link

We discussed a path forward for versioning of this spec, and using submodules in the go sdk to keep track of those version dependencies. We punted on the exact versioning scheme for the go SDK releases and left it up to the person that does it to pick something reasonable. In that context, I would make a stronger case for semver or something that looks like semver, just to play as nice as possible with go tooling.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants