Feature request: clearer (semantic?) versioning; version tags

[dmolesUC]

Given section 4.2, "Guidelines for existing services and versioning of services"

We do not recommend making a breaking change to a service that pre-dates these guidelines simply for compliance sake. The service SHOULD try to become compliant at the next version release when compatibility is being broken anyway. When a service adds a new API, that API SHOULD be consistent with the other APIs of the same version. So if a service was written against version 1.0 of the guidelines, new APIs added incrementally to the service SHOULD also follow version 1.0. The service can then upgrade to align with the latest version of the guidelines at the service's next major release.

I expected to find a tag that would allow me to link to the (presumably stable) 2.2 version, but it looks like Guidelines.md was created at version 2.3 and that version 2.3 is still a work in progress. It would be nice if there was a tagged, stable version one could link to.

[RobDolinMS]

Thanks @dmolesUC3. This is helpful feedback.

Are there other specs on GitHub that you think do this week?

I've seen the Open Container Initiative (OCI) do "Releases" and I've seen the OpenAPI Initiative (OAI) keep legacy versions of their spec in their active repo.

As a potential customer for this, I'm curious if you (or others) have preferences.

[dmolesUC]

Personally I like the OCI approach as it mirrors the way most GitHub open-source projects seem to work. The OpenAPI approach isn't terrible, but as someone with a web archiving background I worry about stable URLs. Right now you can link to blob/master/versions/2.0.md, but if they reorganize their directory structure to, say, blob/master/versions/2.x/2.0.md, that link would break, whereas the OCI blob/v0.5.0/runtime.md would still be good regardless.

(I should probably file an issue on the OpenAPI project. :) )

[garethj-msft]

+1 - this is great feedback.