We should make major releases more often

[braaar]

After reading the blog post "Major Version Numbers are Not Sacred" by SemVer's creator Tom Preston-Werner I have become convinced that validator.js is releasing major versions far too seldomly.

Tom expresses this far better than I could, so just go and read it if you want to understand the rationale for this. I won't try to restate what he writes in that post, but I will bring up some specific points that are relevant to validator.js specifically.

Breaking one validator at a time is not a big deal
I am of the belief that, with the sheer amount of validators in this project (and the fringe nature of some of them), most users will not be affected if we make a breaking change towards one specific validator. When reading the release notes, they can quickly identify which validators have breaking changes and safely bump if they aren't using those particular validators. If they are using that validator, the scope of the change is quite small and they can take steps to migrate fairly easily.

This is obviously easier to do the fewer validators are touched in one release. If we some day decide to fully transition to options objects and break the old way of passing validation arguments for every validator in one huge release it will be quite daunting to migrate to the new code in one go.

Here's a relevant quote from the blog post:

I actually prefer more frequent major versions with smaller sets of breaking changes. There is a real danger in saving up all your significant changes and releasing them in one whopping major version once a year. In the early days of GitHub, when we would need to upgrade Ruby on Rails to the latest major version, it would often take weeks or months to accomplish, even with a dedicated developer on the task. Once, because of how extensive the changes needed to be, the upgrade branch started to deviate so much from the main branch that it became too unwieldy to merge, and we had to throw it away and start over with a different approach. Spreading upgrade work out throughout the year would have saved us a lot of time and anguish.

We haven't had a major version release since 2020
I believe we are putting off breaking changes in an unhealthy fashion. There are many ways in which this project can improve if we allow ourselves to make good changes as they are suggested and contributors are motivated to make things better. If "this sounds nice, but we'll have to wait and schedule it for a major release at some point" becomes the default response to everything we lose some momentum and hype for positive change.

We are arguably breaking this library in minor versions
One thing Tom talks about in his post is that it is a dangerous trend that many projects release breaking changes in minor versions because it feels "too sacred" to release major versions too often. In validator.js we are fairly regularly coming across minor problems in validator code and making fixes. The line between bugfix and breaking change is very fine in this project, since determining the the difference between a valid and invalid payload is the entire goal of this package. Arguably we are making breaking changes every time a validator's code is changed, and in some cases this can be rather significant if the original validator code was overly permissive. We are dishonest towards our users if we release such changes in minor versions, I think.

This comes from a place of love ❤️
I don't mean to be critical of the maintainers here. My wish is to make the job of the maintainers easier and less stressful. I want to relieve you of the hassle of tracking dozens of different breaking changes to try and piece together a major release. I want you to focus on empowering contributors and releasing good changes without worrying about backlash or complaints. I believe that is best achieved by not treating the major version number as sacred.

Let's strive to release version 40.0.0 later this year 😉

[pano9000]

Thanks you for this post, I whole-heartedly agree - as you long as we use proper versioning, the breaking changes should not come to anyone with a surprise (i.e. hoping that people are correctly pinning their dependencies, e.g. in their package.json).

It is especially necessary, as this project has been around for some time already, and of course over time some decisions may have been not ideal in hindsight (e.g. IMHO the mobile phone numbers validator requiring a locale, when there really is no point for that, if you ask me - a simple country code would be the better option here) - but are still carried forward, due to trying to avoid breaking changes.

So +1 from my side, for being more open to breaking changes, accompanied with proper versioning :-)

[simenandre]

If "this sounds nice, but we'll have to wait and schedule it for a major release at some point" becomes the default response to everything we lose some momentum and hype for positive change.

As @mcollina talks about in the presentation «Build a Community, Not a Framework», there's more than code when building a successful OSS project. It's developer experience, product strategy, documentation, licensing, outreach and – release strategy!

And, @braaar, I couldn't agree more about losing the moment and hype – to quote Matteo yet again:

It's all about community

@pano9000 I have had success with automated release strategies, such as Release Please and Semantic Release. Seeing as we're already using conventional commits, I think proper versioning seems relatively easy to get landed :)