Semantic Versioning is a widespread, standardized way to version software. The benefits of using a standard like this aren’t huge, but I think they’re significant enough. Would it make sense to version the two reference implementations according to this spec?
Interesting idea, but Semantic Versioning is defined in terms of API compatibility. For CommonMark, I think the much more pressing question is about versioning the specification.
For example, in topic What is the point of limiting uri schemes in autolinks? I’m proposing a change to the specification that makes it simpler and more consistant. But it changes the result of one of the specified test outputs, sort of a corner-case one at that.
Technically speaking, my proposed change would have no impact on the API of an implementation, but it does change the expected output in a slightly non backwards-compatible way. How do you apply semantic versioning to that?
It is a breaking change, and thus a bump in the major version (from 1.0.0 to 2.0.0).
In regards to using semantic versioning here, I am unsure if that’s a good idea. CommonMark has a single input (a block of Markdown formatted text) and a single output (a block of valid HTML or syntax tree). Every change to the spec will result in a output that is different from the previous version, given the input stays the same. In my understanding that makes every change a breaking change.
This means every change is expected to bump the major version number (1.0.0 → 2.0.0 → 3.0.0 → …) and only things like performance fixes will change any of the other numbers as defined by Semantic Versioning.
1 Like
If the current spec for CommonMark is still were considered final 1.0, then I agree. But Sematnic Versioning has a key provision for “pre-release” strings that I suggest would be essential to successfully applying semantic versions to a community-driven project.
The spec seems still to be in a state of flux, so I’m not sure who/when/how a final Version 1 version gets (or has been) declared to use as the baseline for considering what constitutes a breaking change.
I think getting @jgm to adopt a pre-release string for ongoing edits would be essential to making semantic versioning work for the spec. In addition, considerations still under discussion on the normative vs. informative topic are essential to prevent semantic versioning runaway as @Zengat described.
Its a topic worthy of the attention of the core contributors, and I suggest it belongs in the Spec category rather than Implementation.
But it does change the expected output in a slightly non backwards-compatible way. How do you apply semantic versioning to that?
They would bump major and release 2.0.0.
This is exactly why semver isn’t applicable here. If you strictly follow it, you need to bump major version on every second change you make, because your changes usually break something.
It would probably make sense to try and apply this versioning to the spec itself. But for reference implementations please take my advice and avoid semver entirely. It’s more trouble than it’s worth.