Release between v0.3.9 and v0.3.15 broke semver

[dominikwilkowski]

Hi there

First of all thank you for the hard work on marked. I do appreciate this package a lot and want to acknowledge that.

I noticed that between v0.3.9 and v0.3.15 (I assume v0.3.12 as it mentions Improved links) marked started parsing email links and wrapping them into links. A welcome change and it seems to work great but it certainly broke semver.

A change like that is a major change as the same input yields different output in my personal opinion. But even if you disagree on major it is at the very least a minor change as it adds a feature and most certainly not a patch.

I found it as it broke our integration tests in older node versions (we test several) which don't support the package.lock file and installed a newer version of marked that our fixtures hadn't accounted for. Not an easy thing to track down :)

Anyway hope this helps as a hint.

[UziTech]

Thank you for reporting this but since marked is still in beta (0.x) semver allows any non-breaking changes to update the last digit instead of the middle one.

[dominikwilkowski]

Fair enough. I missed that it's still in beta. Doesn't say it in the readme. To make that clear maybe call it v0.3.0-beta.16 instead?

Food for thought?

[dominikwilkowski]

You're of course quite right though:
https://semver.org/#spec-item-4

[joshbruce]

Just want to add more detail to make sure folks who stumble upon this later. Semantic versioning is more about APIs not outputs. This question and point falls under semantic versioning 3 and 4.

3. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

4. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Because the package contents of previous versions was not changed, we are still abiding by semantic versioning 3 and consumers can take the option of using the previous version. To the best of my knowledge the APIs have not changed much, if at all, yet; therefore, still okay under the major zero concepts with the added benefit of not changing the APIs.

There are three milestones we are working toward, which will indicate more drastic changes: https://github.com/markedjs/marked/milestones

• 0.4.0: No known defects (this includes security and I/O generated by marked). We will be working toward compliance with two specifications: CommonMark and GitHub Flavored Markdown (which is, essentially, CommonMark + extensions).
• 0.5.0: Architectural changes and improved extensibility.
• 0.6.0: At which point we will be focusing on changes that improve how developers interact with and contribute to marked.

Because development on the library stalled a bit, and for a long period of time, I know many of our users may have felt it was stable; however, it's more like it just didn't change while still having some issues.

We have also generated the RELEASE document, which describes how are extending semantic versioning for our context and purposes.

Thank you again for submitting this issue.

[Feder1co5oave]

@dominikwilkowski thanks for writing, we greatly appreciate your feedback 👍
All of you made good points. I'll just throw in some of mine too.

• Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

  This is absurd. Or maybe developers should try to release 1.0 much earlier in the process. marked has been in 0.x since its birth, several years ago.

• Since 0.x is considered a 'development' release, there's no need to add -beta to it.

• I think @dominikwilkowski is referring to 00f1f7a for the new email autolinking. I can see why in his p.o.v this is a "breaking" change but I actually considered this a "fix", because marked supports gfm extensions and I added the email autolinking to comply with it.

• marked API hasn't changed in a long time. I think the last change was the Renderer refactor but that was backward-compatible. So no major version upgrade was needed. (when you're in 0.x, even a minor version upgrade can mean an API change - version upgrades have a different meaning if you're in 0.x and that can be confusing!)

• The default way of using marked as a dependecy is by using the ^ in package.json (this is done by npm install marked): "marked": "^0.3.15". ^ means "compatible". According to semver:

  Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X.
  So in 0.x a minor upgrade would mean breaking changes, whereas in 1.x it wouldn't.

I'm shifting toward thinking that the email autolinking should have deserved a minor bump, since it can change the output significantly (as happened to you), but since we're in 0.x that would be too much.

---

Proposal

Considering the points above, my proposal to @joshbruce and @UziTech is this: we should accelerate the bump to 1.0, declaring it the new "no defects" release instead of the 0.4. Until that, we bump the minor version for every "breaking" change we introduce (like the case with email autolinks). The 1.0 will be API compatible with 0.3, but it will be safe, almost 100% compliant with commonmark and gfm. No extensions or frills.
After that (and we can develop it in a parallel branch) we aim to 2.0 for extensions, modularization, API change... that would be marked 2.0!

I don't know if this would be 100% compliant with semantic versioning, as I think the 1.0 should be the stable public API, but I think we're free to decide the API won't change in 1.0.

Pros:

• we release the 1.0 much early
• minor bumps will reflect more correctly the development process until 1.0
• marked 2.0 will be awesome 😄

Cons:

• by bumping minors in 0.x we declare incompatibility even when it is in fact compatible (but we can still bump patches for security fixes and transparent changes)
• marked 1.0 won't be the "final" API because we'll be working on marked 2.0 from early on
• we break the current release pattern of marked, where patches are released, unless they bring big changes (the Renderer refactor bumped us to 0.3.0)

[dominikwilkowski]

Thank you all for engaging with me on this. The 0.x problem has been around for a while; see here:
semver/semver#221

I think moving to a new major 1.0.0 bump sooner rather than later will only benefit the developers so they can mange the versions easier than staying at 0.x until the bitter end :)

We shouldn't be afraid of breaking changes when we develop and maintain a software and semver helps us with that. Staying on an unstable 0.x will just make it harder for the devs as they need to pin their versions. That's fine for a little while but after years it may become problematic.

On both of your points that the API is still the same therefor it's not a breaking change, surely when you return something different you break things, especially for an API that is solely concerned about how to format a string. But I take your point and don't want to run into semantic discussions.

The best point I think here was made by @Feder1co5oave

I think @dominikwilkowski is referring to 00f1f7a for the new email autolinking. I can see why in his p.o.v this is a "breaking" change but I actually considered this a "fix", because marked supports gfm extensions and I added the email autolinking to comply with it.

That makes complete sense especially in context of the package still being developed. I was only caught in this issue because I wrongly assumed marked was stable as I've been using it for years.

Bumping to 1.x would certainly make me happy :)