search

reconciliation-api / specs

Specifications of the reconciliation API
https://reconciliation-api.github.io/specs/draft/
31 stars 9 forks source link

use semantic versioning for protocol versions (?) #135

Closed awagner-mainz closed 3 weeks ago

awagner-mainz commented 1 year ago

In my experience, the semantic versioning scheme has proven quite useful and widespread. However, it mandates that version numbers MUST include a patch version (i.e. have three parts <major>.<minor>.<patch>). This holds even for zero version numbers (0.*.*) that otherwise makes version naming in the initial development phase free from many constraints.

Would it make sense for this spec to follow (and declare that it is doing so) the semver spec?

wetneb commented 1 year ago

I don't know how widespread semantic versioning is for specs… to be honest it felt a bit over the top even to introduce a minor version number in the first place, perhaps a simple numbering would have been enough. As a spec user maybe I'd find it a bit frightening to see that some specs use the full blown semantic versioning scheme because it sort of implies that the spec authors intend to do a lot of different versions, which must be hard to keep track of as an implementer.

As far as I am concerned, I don't have the intention to publish a lot more versions of the specs: 0.1 was what we started with, 0.2 was all the backwards-compatible improvements we could think of, and the next one will be "the clean one" with the things we could not fix without making a breaking change. I think specs are never perfect and their value lies in the reach of their adoption - and stability of the specs helps adoption.

awagner-mainz commented 1 year ago

I was a bit hesitant myself - and pretty much for the same reasons that you describe.

I am currently working on a client that I want to support multiple versions and I am using a semver library to choose between branches of my code. This library won't work with invalid semver version numbers - but the workaround solution I now am using is to "inject" a ".0" patch number if there is none. That's not too much of a problem I think.

I could very well understand if you wanted to keep this out of the spec, but wanted to bring it up in case you had stronger ambitions with regard to semantic versioning.