Semantic versioning
A brief primer on semantic versioning
We've been following a WordPress-style model where our major release are the second number, but only halfway really, since we never really came to grips with the idea that 3.0 would be no different than 2.9 or 3.1. This versioning system is for historical reasons. Vanilla 2.0 was a rewrite of Vanilla 1.0, so we were always reluctant to make the 3.0 jump. But it's upon us one way or another soon, since a version like "2.11" is too silly and we're running out of digits.
I'm also running into difficulty explaining the `.dev` in our cloud release versions to Enterprise customers that can see our source code and wonder why we're running "dev" code in production. That was the only reasonable way I could find to unify cloud and open source versioning in a continuous release scenario, short of semantic versioning.
I'm proposing we rip the band aid off and go full semantic versioning after the 2.8 release. This is a solved problem and I'm tired of dancing around it for fuzzy historical reasons.
Thoughts?
Comments
-
The biggest change, from a developer's perspective, is that we would need to more carefully monitor for, label, and communicate ANY backwards-incompatible changes so that we can increment the version correctly. In reality, we've already discussed this as a pain point between R&D and support that we need to resolve regardless, so it doesn't seem like an extra hurdle.
0 -
My 2 cents, Vanilla 3.0 should be tied to something big - so I think the KB release would be worthwhile, or did you not have it tied to anything major. I was looking at the calendar and July 22, 2010, was the day Vanilla 2 was announced. Would be a great day to announce Vanilla 3 :)
1 -
Vanilla 3.0 should be tied to something big
So you are arguing against semantic versioning, then.
0 -
I think the KB release would be worthwhile
I don't understand this.
KB is for cloud, where we don't really advertise a version number typically. We're also numbering is separately for internal purposes, with 1.0 being the first release.
"Vanilla 3.0" is primarily an open source moniker, where there won't be a KB release at all.
0 -
I guess I'm arguing against it for full numbers just for the sake of them. I think Vanilla 3.0 or Vanilla 4.0 or whatever version should be something of note - at the same time I've always thought things like 2.11 were silly as well.
I guess it's my historical bias and marketing mind always thinking a whole number version needs to be special.
In the end, I'll go with what makes your life easier -- but I don't really have a dog in this fight, so to speak :)
0 -
I support semver if for no other reason than making our version numbers actually mean something. Right now, they essentially represent an arbitrary state of our codebase. If we use semver appropriately, comparing numbers will help set expectations of our users (OSS and Enterprise) on how much has changed in the product between those versions.
I'm also a fan of semver, because we can better draw a line in the sand when we want to introduce BC-breaking changes in Vanilla. It's easier for users to recognize that upgrading from v3 to v4 might break their site/addon (and obvious to users familiar with semver), versus upgrading from v3.1 to v3.2. We put a long tail on our BC support with no truly great way to communicate when that support vanishes. As a result, we feel compelled to indefinitely maintain that support. Semvar would help that communication, as well as (hopefully) emboldening us to start sloughing off some ancient BC in earnest.
1 -
Semantic Versioning
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
We should totally go forward with that. It's less insane (read more logical) than what we have right now.
1 -
I like that @D̸̨͝ą̸͂a̵͍̔z̴̙͋K̶̤̀u̷̢̇ - If that is what @Linc meant. I hadn't read it that way 😀
0 -
It is; it's included in the article I linked.
We break backwards compatibility enough (usually in minor ways, but it doesn't care how big it is) that it would increase our major version number fairly quickly, I think.
1 -
I’m wholly in favour of semantic versioning. There are a few things I'd like to make clear though:
Strictness
I'm ok with not being too strict in what is a breaking change:
- Methods and classes marked with
@internalshould be considered as private methods. - Adding a CSS class to an element could technically be considering a breaking change in our world customizations and custom theming. I don't think something like that should be considered a breaking change.
LTS for open source versions
@Ryan Touched on this slightly with discussion of our long tail of open source support. I'd like to make a clear distinction of what the support timeline would be (this would be the timeline for how long we back-port security fixes to open source releases).
We could probably play with how long we do these for, but I'd think we could look at it like this:
- Open source always has an active release. This is the latest final point release that we make. If we didn't do the whole dev release thing we would have probably called many of the early
2.8.deviterations2.7.xand the time we decided to make a big open source release would be2.8exactly is it is now. - Open source sometimes has a long term release. This can be done when update our minimum system requirements. Eg. We're bumping our minimums to PHP 7.1 and hopefully our MySQL version up, so we may decide to offer offer a period of security patches to a previous release no longer on cloud similar to what we did with 2.5 (PHP 5.6 EOL). If we don't skip an OSS release like we did with 2.4 or 2.7 this shouldn't be an issue going forward.
- Cloud releases get a ¯\_(ツ)_/¯. I don't particularly care what we call these because we don't have to do too much LTS on them.
We should probably keep the LTS open source versions minimal. I don't even think we necessarily need it for every breaking change. Only some of them. As an example Node.JS & Ubuntu only do LTS on even numbered versions but I don't think we necessarily need to tie ourselves to it.
Example.
3.0 - Has new minimum PHP version so 2.8 gets a 6 month LTS (or less. @Linc probably has the best feel for these timelines).
3.x.x - We only ever worry about the latest 3.x.
4.x - Some breaking changes, but users on the 3.x trunk are expected to update to here if they want continued security patches. We may still have a brief period of support for 3.x due to timelines with our enterprise clients, but we should try and minimize this.
Some interim time - Maybe LTS for for the old PHP/MySQL version is done. This doesn't mean we need another LTS yet.
5.x - Some breaking changes + PHP 7.2 minimum version. Time for another LTS.
Deprecations and Major releases
We have a good chunk of deprecated functions at the moment. We probably need to do a bit more triage here. I have a whole slew of previously deprecated functions that I put in our 2.8 release notes, but if there's any more that we might want to be rid of in 3.0 we may want to do a 2.9 adding more of them. @AlexanderKim this would be your chance. Our rules for deprecation currently though are to remove all of our internal usages (vanilla & vanillaforums github orgs).
0 - Methods and classes marked with
-
@Adrian we've had some breaking change in all of our "minor" releases and also had major features in most of them. If I were to re-number them:
- 2.5 => 3.0 - New dashboard UI (plus some old broken dashboard pages), IPv6 support. APIv2 beta.
- 2.6 => 3.1 - Dashboard APIv2 docs + more endpoints, category following
- 2.7 => 3.2 - More APIv2 endpoints + Rich Editor Beta
- 2.8 => 4.0 - New default base theme (keystone) + new default editor (rich editor) + breaking changes (some deleted deprecated functions/classes).
Caveat: There definitely some breaking changes in what I'm calling 3.1 but I think we were calling APIv2 beta as of the 2.5 release and if we weren't we should have.
0 -
I'm just a dolt. I hadn't noticed the link you added @Linc . As I mentioned, it's not anything that impacts me one way or the other - but it's clearer now and makes sense.
0 -
I like the way browsers do it where they upgrade a major version on a schedule (in their case every 6 months). This also agrees with semantic versioning, but serves another purpose.
In the past we've been reluctant to to update our major version because that has traditionally come with a marketing push which is what @Adrian is talking about. I think at this point the software version as a marketing moniker is sort of outdated. I think the reason browsers started going to a rapidly incrementing version is to take version numbers completely out of the browser wars. No one cares that Chrome is 6 versions higher than Firefox (version 71 vs. 65). If we are to increment our major versions I think we should go this route and plan to increment the major version. We can even just declare the change as moving our minor version into the major slot. I think React did this.
@Lvez once made a very good point: "SASS doesn't have versions". I really like this mantra.
1 -
I like the way browsers do it where they upgrade a major version on a schedule (in their case every 6 months). This also agrees with semantic versioning, but serves another purpose.
I'm pretty sure for chrome it's every 6 weeks actually, but point taken.
0 -
I've announced a change to semantic versioning to the open source community.
0 -
We'll use a build number of YEAR.RELEASE_NUMBER appended to the last open source version release to differentiate our cloud releases.
So our next cloud release will be
2.8+2019.003. Colloquially, that is simply "2019 release #3". The release number will increment all year independent of the version number (so if we release 3.0, the build counter doesn't reset). That allows us to talk about our releases to customers (and internally) completely independent of the open source version number, while still making sense for version comparisons in code.This is a plausible numbering scenario for cloud this year:
- 2.7+2019.001 (the 2.8.dev.6 release on Jan 17 if it were retconned to the new system)
- 2.8+2019.002 (current release retconned to the new system)
- 2.8+2019.003
- 2.8+2019.004
- 3.0+2019.005 (simultaneous with OR after 3.0 open source release)
- 3.0+2019.006
- 3.0+2019.007
- 3.1+2019.008 (simultaneous with OR after 3.1 open source release)
- 3.1+2019.009
- 3.1+2019.010
Enterprise customers may get non-consecutive release numbers. For instance, they skipped 001 and will begin the year with 002.
Note that I made the release number 3-digits primarily to make it obvious it isn't a month identifier. I don't actually expect us to hit 100 releases this year.
Ideally, when we fork for release, we'll increment master +1 release number immediately to differentiate it (rather than waiting for the fork and changing it on the new branch every time).
0
