vas
March 13, 2025, 12:57am
1
opened 02:10AM - 03 Feb 25 UTC
All [jokes](https://talk.commonmark.org/t/when-do-you-think-well-ship-1-0-of-the… -commonmark-spec/2797/20) aside, six years have passed since @jgm [wrote](https://github.com/commonmark/commonmark-spec/issues/561#issuecomment-473683793):
> 1.0 implies stability. We're not there yet: there are still some changes that need to be made.
@jgm, I don't know if your definition of stability has since been met. If it has, no further case need be made. If it is on the verge of being met, i.e. months not years, then there's no point in changing policy and this issue can be closed.
Otherwise, here are arguments for calling what we have now "v1.0" anyway:
- Let's say that CommonMark reaches stability in 2027. Version 1.0 is announced shortly thereafter. Will there be projects that will have been waiting patiently eight, ten or fifteen years (CommonMark's inception to 2027) for 1.0 stability, that in the meantime had gone with some other syntax willing to call itself at least v1.0, that will then suddenly jump onto the CommonMark train?
I doubt it. Projects by now have made their decision, Yea or Nay.
The Yeas are of two kinds: Those that implemented whatever version was the latest when they adopted CommonMark and don't follow updates, and those that do follow updates, treating CommonMark as a "living standard" à la HTML5.
The Nays at this point aren't going to change their mind when the number changes from 0.31.2 to 1.0. Most of them are doing whatever GitHub is doing, itself a moving target. GitHub has abandoned staying in sync with CommonMark[^1]. It is now driven by business expediency rather than principle, stability or community. It's even balkanizes itself, as teams responsible for different features don't seem to care even about cross-GitHub consistency.[^2]
In all the ways that matter CommonMark is stable. The aforementioned Yeas wouldn't have adopted it if they thought otherwise. They treat it as a `v1.n.n` even if it calls itself `v0.n.n`.
- CommonMark can still do patch updates (v1.0.1) and minor version updates (v1.1). For example the proposed CJK emphasis change, if effectively a backwards-compatible feature addition, might be v1.1.
If there are backwards incompatible changes that must be made (which would be a little surprising since I understood the goal to be maintaining compatibility with Gruber Markdown with a few exceptions decided long ago), then those could be developed on a v2-alpha branch.
Let v2-alpha play the role of the WIP syntax that the v0.n.n series plays today. It can take as long as it takes.
Alternatively, don't be shy about increasing major version numbers. For example:
| instead of | we'd have |
| ---------- | ------------------------------------------------------------ |
| v0.33 | v1.0 |
| v0.33.1 | v1.0.1 or v1.1, depending on the nature of the change |
| v0.34 | v2 or v1.1 or v1.2, depending on the nature of the change and the last version number |
| v0.35 | v3 or v2.1 or v1.2, v1.3, likewise depending |
As you can see, the right-side sequence can be far more expressive about the nature of each change than the left-side sequence.
- Holding off on calling it v1 even after all these years implies a degree of uncertainty and possibility of significant breaking changes greater than reality.
[^1]: They have abandoned their [CommonMark-based GFM spec](https://github.github.com/gfm/). I haven't checked, but I would not be surprised if the timing lines up with the MS takeover.
[^2]: The supported syntax for repository `.md` files, for Issue descriptions/comments, and as implemented by their REST API, differ.
Please don’t pile “i agree” or “no!” comments onto the GitHub issue unless you have a new argument for or against, or some other useful additional info. JGM doesn’t need the noise. Use the emoticon reactions to register simple votes.
1 Like