The case for calling it Version 1.0

[vassudanagunta]

All jokes aside, six years have passed since @jgm wrote:

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¹. 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.²

  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.

Footnotes

1. They have abandoned their CommonMark-based GFM spec. 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. ↩

[jgm]

Certainly there has been a lot of stability for years, in the sense of lack of any major changes. On the other hand, some of the issues that seemed unsettled before (and made me hesitate to call it 1.0) are still unsettled.

I'm open to calling it 1.0, though. I'm not sure it matters greatly for anything.

[vassudanagunta]

Similarly if the unsettled issues can stay unsettled for so long, can their settlement matter that greatly?

So many mature projects have deemed it sufficiently stable and reliable to have adopted it, not as something internal and hidden from the user, but as syntax for their users to use. I think the symbolism and acknowledgment of reality matters, for prospective new users, and because a confident community standard has a better chance against proprietary hegemony.

[Crissov]

For what it’s worth, I had started to write specifications for several extensions a couple of years ago but then stopped my efforts because I wanted to wait for an official 1.0 release to base them on. Also it was my impression at the time that such extensions would actually have the chance to be incorporated into a later major version.

That means: yes, calling it 1.0.0 does matter, perception-wise.

Just pick any resolution for the remaining half dozen open issues! It will be fine either way. That’s what ten years of ambiguity teach us anyway.

https://talk.commonmark.org/t/issues-we-must-resolve-before-1-0-release-6-remaining/1287

https://talk.commonmark.org/t/issues-we-should-resolve-before-1-0-release/2136

[wooorm]

I’m 👍 on cutting 1.0.0 right now. I think that’s fine.

I’d also think that we could spec a generic directive extension mechanism:

:cite[smith04]

::youtube[Video of a cat in a box]{vid=01ab2cd3efg}

:::spoiler
He dies.
:::

we could do that in, say, a month; it would be a viable answer to about 50% (?) of the open requests; plus it would be something exciting to put into the release.

[digitalmoksha]

I'm also very much in favor of moving to a 1.0. I think it's time.

[jgm]

There are still some serious very basic issues, e.g.
#460

In addition, it would be nice to modify the emphasis parsing rules so that they are more useful for a quarter of the world's population. Here we have made considerable progress and seem to be converging on a good solution:
#650

Of course, we could just leave these issues unresolved in 1.0 and deal with them later.

I am not in favor of hastily adding an syntax for generic extensions in 1.0. That wouldn't make sense. If we do mark 1.0, it should be in recognition of the de facto stability of the spec.

Of course, I like the idea of a generic mechanism for extending the syntax, which is why something similar is included in pandoc's markdown and djot. Maybe that could be considered later. Other extensions that are arguably needed (and not easily handled with a generic extension mechanism) are a table syntax, a math syntax and a definition list syntax.

[wooorm]

I wanted to mention directives to prevent the discussion from getting into what should and shouldn’t go in. Directives go very far. For me, math + definition lists can be done by directives or html (or for math: ```math even).
Backporting (some of) GFM might be a good idea (later). I’d guess most folks don’t know tables are GFM instead of CM.
So reiterating: 👍 to 1.0.0 now, much can be added later. If the plan is to get things in before 1.0.0, then I’d prefer only directives for now.

[vassudanagunta]

In addition, it would be nice to modify the emphasis parsing rules so that they are more useful for a quarter of the world's population. Here we have made considerable progress and seem to be converging on a good solution:
#650

If more CJK-friendly emphasis is truly close, it may make sense to wait for it. It would send the message that CommonMark considers the issue important, and it would increase the likelihood and speed of adoption across CM implementations.

Alternatively, as part of the v1.0 announcement, include a statement that commits the next version, v1.1, to address CJK issues.

[vassudanagunta]

I suspect that the new CJK rules will need a trial period, with real-world usage feedback from that quarter of the world's population. In which case a v1.0 with current (long-standing) emphasis rules, and a v1.1-beta with the new rules might be best.