Plans for semantic versioning

[thejasechen]

Are there any plans for weasyprint to follow semantic versioning conventions? It would help immensely in managing dependencies in larger projects.

[liZe]

Are there any plans for weasyprint to follow semantic versioning conventions?

Short answer: no. And the long answer is long!

(The following paragraphs are just my personal point of view. And I should have written them earlier.)

When version 43 was released, my first idea was to release 1.0.0 and to follow semantic versioning. After all, WeasyPrint is just another library with an API, and it would benefit from that. By the way, I'm the maintainer of many other libraries (CairoSVG, tinycss2, cssselect2, pyphen…), they all follow SemVer, and I'm really happy with it.

When Firefox and Chrome changed their numbering (in 2008-2011) and decided to have a major release each time, at first I was surprised, and I've even thought that it was a stupid decision: "This version number will be growing fast, it's ridiculous, we can't know if big changes are happening, the API doesn't break at each version even if the major number is incremented, it's just a marketing trick, blah blah blah" (sorry for the noise, I was young then).

Now, I agree with them.

Why?

It would help immensely in managing dependencies in larger projects.

That's why. Using SemVer for WeasyPrint would just give an illusory help.

Semantic versioning is useful if you can "promise" your users that:

• when a patch version is released, it's just a backwards-compatible bug fix,
• when a minor version is released, it's just new functionalities in a backwards-compatible manner,
• when a major version is released, there are API changes.

If WeasyPrint users were just using the API for the sake of using an API, then I could hold this promise: if the public API breaks, I release a major version, if it doesn't I don't. But the "real" API of browsers is not the API: it's the way HTML and CSS is rendered. Some users rely on the Python interface, for sure, but all users actually rely on the HTML/CSS interface at least as much as they rely on the Python one.

So, I could use SemVer according to the Python API changes, but that would be a lie because even minor versions could break the rendering. As a library user, that's my worst nightmare: update a library with a minor change, see that the API didn't change and see unit tests pass, update in production and see that it actually broke many things for my end users (I'm pretty sure you've been through this too if you use JS libraries 😄).

That's why I've chosen to hold another promise: each WeasyPrint version is a major version, as it breaks things. I know it's sad for users, they have to read the changelog each time, they have to check that the rendering is OK, often manually, and I really wish it could be different. But the reality is that even supporting a new CSS property breaks rendering in real life use cases: as many users generate documents from pages that are rendered by "real" browsers too, they rely on the fact that the property is supported on browsers and not supported on WeasyPrint. We've even broken one of our examples (#851) by improving the flex rendering…

That's how I've understood that the Chrome and Firefox devs were not stupid 😉.

WeasyPrint actually follows SemVer, with only major releases. SemVer is a really good idea, but when it is not adapted, maybe it's a good idea not to blindly follow it. I don't think it's adapted for WeasyPrint. Adding .0.0 behind each version would just be pedantic, it wouldn't really help. And maybe you'll agree that the SemVer version numbers (that are actually no the same as their erratic Git tags) would be more friendly with the useless zeros removed from them.

[thejasechen]

Appreciate the thorough answer here! When you put it in context, the decision to follow this version scheme makes a lot of sense.

Since weasyprint will be following the current convention, I think it would be great to have snippets of your explanation in the README for posterity sake.

My only argument for following semantic versioning (even if it means adding .0.0 on every version release) would be so that it is transparent at a glance that each new version will entail a breaking change.

It is apparent that much thought has been put into this, I have no quarrels and will opt to close this issue.

[liZe]

Since weasyprint will be following the current convention, I think it would be great to have snippets of your explanation in the README for posterity sake.

You're right, in the README or at least in the documentation.

My only argument for following semantic versioning (even if it means adding .0.0 on every version release) would be so that it is transparent at a glance that each new version will entail a breaking change.

I hope that putting this information in public documentation will help people wondering why WeasyPrint doesn't follow SemVer.

It is apparent that much thought has been put into this, I have no quarrels and will opt to close this issue.

That was an interesting question and I should have written this a long time ago, so thank you for the talk!

(I reopen this issue for now, and will close it when the text is added somewhere.)