Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Plans for semantic versioning #900
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.
That's why. Using SemVer for WeasyPrint would just give an illusory help.
Semantic versioning is useful if you can "promise" your users that:
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
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
It is apparent that much thought has been put into this, I have no quarrels and will opt to close this issue.
You're right, in the README or at least in the documentation.
I hope that putting this information in public documentation will help people wondering why WeasyPrint doesn't follow SemVer.
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.)