Version numbering

[gasman]

Hi all,
I'd like to share some thoughts and seek your input about how Wagtail should deal with version numbering in future.

As you may know, we make a new feature release of Wagtail every three months. I think this strikes a good balance between getting new features into users' hands without a massive wait, and not tying up too much of our time with release management and testing (plus not making it a massive chore for users to keep up with upgrades). Sticking to this schedule means that some releases inevitably end up being bigger than others, since the resources we can allocate to Wagtail development vary from month to month, and we make a point of not holding up a release to get "that one killer feature" included. In any case, we currently always bump the minor version, e.g. 2.14 -> 2.15.

We don't follow semantic versioning - we regularly make breaking changes in these minor releases (and, hopefully, give enough guidance in the release notes that this isn't a massive burden on developers). Wagtail development is fast-moving enough that if we were to commit to only making backwards-incompatible changes on major releases, we'd either be hampered when doing important development like workflows and the telepath StreamField rebuild, or we'd be on something like version 15 instead of 2.15 by now.

While this arrangement does seem to work quite nicely for us, we've recently been feeling a few negative effects for the Wagtail ecosystem and community:

• Developers of third-party packages don't know in advance how drastic the changes in the next 2.x release are going to be, so they have to be conservative when specifying the compatible Wagtail version range and avoid promising support for future versions before they're out. This means that on every new Wagtail release, they have to test their package and make a new release with the version range updated - which takes time, and users of that package have to wait before upgrading to the new Wagtail release.
• Site owners don't always have a clear idea of what impact a Wagtail upgrade will have on the editor experience - if you upgrade from 2.14 to 2.15, is it going to be a total revamp or just some tinkering with low-level internals?
• Release candidates don't get as much testing as we'd like from the community, possibly because a new 2.x release is just a routine event and nothing to get excited about... as a result, we often have to quickly follow up a feature release with a 2.x.1 bugfix for things that really should have been caught earlier.
• Right now, we don't have a clear idea of what a Wagtail 3.0 release would entail, but it feels like it'll have to be something really big and radical, which gives us some psychological pressure to cram in more breaking changes than we really should (because it's going to be a long time until 4.0 happens, right...?)

With that in mind, I'm wondering if it's time to make greater use of the major version number. Exactly how it would work is up for discussion (so let's have that discussion here!) but I'm imagining something like this...

• We continue to put out a feature release every three months.
• We increment the major version number whenever there's a feature that either makes a significant visible change to the editor interface, or breaks backward compatibility. As a rough indicator based on the last few releases: the changes in 2.13 (new streamfield and commenting) would have warranted a new major version; 2.14 wouldn't, and 2.15 would (bulk actions). So, we could expect 1-2 major versions per year.
• We avoid breaking changes in minor releases. Where possible, changes will go through our deprecation process so that initially, code relying on the old behaviour will still work and just output a warning; the old behaviour will then be removed in the next major release. (As an exception to that rule - if a feature is deprecated in the last minor release before a major release, we still want to give users a two-release window to update their code, and so it will remain in that major release, and be removed in the next major release after that.)

One slightly odd consequence of this is that we might not know whether the forthcoming release is (say) 3.3 or 4.0 until quite late in the day... if a major feature is close to completion but may or may not make our three-month deadline, we won't bump the version to 4.0 until it lands in the main branch. As a result, in the days leading up to the release candidate we might think we're on course for releasing 3.3, but then the major feature lands and the release suddenly becomes 4.0 instead. But maybe that's not a bad thing!

Interested to hear everyone's thoughts - does the current release cycle work out well for you and your organisation? Would it help for us to adopt something closer to SemVer? Or would the unpredictability make things worse?

[vsalvino]

Great write-up Matt, I agree with your proposal for the semver style releases. Being able to specify 3.* compatibility is a huge win for 3rd party package publishers and users, and should help strengthen the wagtail ecosystem.

My only thought is to the fate of LTS releases. Should they be done away with entirely? My thought is that the last minor release before the next major release be retroactively designated LTS and continue to receive fixes for 6 months following the major release. For example:

• 2.15 comes out Nov 1, 2021.
• 3.0 comes out March 1, 2022.
• At that time (March 1, 2022) - 2.15 is designated LTS and will receive only critical fixes for the next 6 months (until Aug 1, 2022).

Such an LTS process should provide enough of a layover period for sites and package maintainers to switch to and/or support 3.x.

[dragon-dxw]

👍 for Semantic Versioning.
As someone who has upgraded Wagtail a few times on a relatively stable website, I want to be able to use Semantic Versioning to understand how much risk and/or effort it's going to be to upgrade. The biggest change that's personally impacted me recently is the database backend deprecation of the postgres search backend in favour of the new one; I'd definately appreciate a major version bump somewhere between it being non-deprecated and being removed.

I'm not a fan of features bumping the major version; although it can feel anticlimatic to do a lot of work to make a feature backwards compatible, it's good to know existing tooling should work fine with the newest editor experience.

I do appreciate the desire to be able to celebrate achievements with a shiny new version number, though, so here's my wild proposal: Releases with editor-centric features get names, something more than a sequence of numbers to excite people when they see it in the editor interface.

As always, thank you all very much for all your work, whatever number you put on it!

[bruecksen]

@gasman thanks for the great input. I'm also absolutely in for the semantic versioning. I just updated a quite old wagtail system today and needed to go through all the 2.1x releases to find out if I need to do something. Even tough it went super smoothly I didn't even had a rough idea of how long this would take.

I also like the idea to make a new major release if there is a significant visible change in the editor. This would help a lot to update the editors if an update was introduced that relevant for them. As well I see a good chance in more testing contribution if the community member could see what kind of new release this is.

Sorry I can't contribute much beside saying this is going in the right direction :)

[thibaudcolas]

I love the proposal, as we’re already making a lot of efforts to avoid breaking changes I’m sure following semantic versioning will be a natural evolution.

There are two things I’m wondering about:

• For breaking changes – we should probably make more of an effort to consider UI changes as well as Python, as that would impact upgrade-ability of any customisations (3rd-party packages). We don’t have much of an API for Wagtail UI components at the moment though, so it feels hard to manage in the current state of things.
• Removing deprecated code in major versions – is it a concern we wouldn’t know in advance when the next major version would be? I suppose we wouldn’t want to keep deprecated code around over too many months. I feel like this is unlikely to be an issue but thought I’d check what others think.

[tomkins]

As someone who generally prefers to follow LTS releases, something similar to Django's release pattern would be ideal - but still keeping Wagtail's current support lifespan given the number of releases in a year. Having a 3.0 which drops compatibility shims, 3.3 as an LTS, then 4.0 dropping compatibility again would be an ideal flow for me. It's predictable, and something which helps when it comes to sites you want to continue running - but don't want to invest a huge amount of time in.

Whilst I'm saying this, I wouldn't worry too much if minor version bumps (3.0 to 3.1, 3.1 to 3.2) includes some incompatible changes - as long as there's instructions on how to upgrade through these versions, which is pretty much always the case anyway.

Even with semantic versioning you need to test every release, there's no guarantee that code which appears to be compatible with multiple versions doesn't end up causing an annoying regression.

[lb-]

Another take is to adopt semantic versioning but align with the calendar year, similar to Black.
https://black.readthedocs.io/en/latest/the_black_code_style/index.html#stability-policy

This kind of boxes us into (major breaking changes once a year), but it may also provide a nice framework for how we plan releases, core updates and features. Anything super new can be behind experimental flags for testing/refinement until it goes out in the next major release.

We may need to revisit the deprecation policy though, when features are dropped we currently have two releases of 'warnings' before the code is actually removed.

A year would look roughly like

• 23.0.0 - Jan 2023 - contains breaking changes, larger update probably required, aim to support the latest Django also out in Dec/Jan
• 23.1.0 - Mar/April (Q1)
• 23.2.0 - June/July (Q2) - Maybe this could be the LTS each year, goal to have some larger features sitting in experimental
• 23.3.0 - Sep/October (Q3) - goal to have all larger features for the following year sitting in experimental
• 23.4.0 - December (sometimes, not every year) - Q4

[tbrlpld]

If Wagtail is going to go the CalVer route, I think using the full year would be nice to make it more obvious what the number stands for. I know it's 2 more characters to type that won't change in any of our lifetimes (assuming mind uploads are not becoming real in that time), but it's nice and explicit. Also Y2K bug 🙃

[vsalvino]

I'm personally against the CalVer scheme. Calendar numbers have no relationship to magnitude of changes. For example 23.1 might only have one tiny minor change, 23.2 might have a major change such as the new editor UI. The fact that they both came out in 2023 has nothing to do with the changes themselves. I've always thought calendar versioning only makes sense for time-sensitive data, such as timezone definitions, antivirus definitions, language specs, etc.

[gasman]

I'm with @vsalvino - a calendar-based system would just place arbitrary restrictions on when and how we can roll out breaking changes, rather than being able to do what makes good engineering sense.

[gasman]

Thanks all for the feedback. A few assorted thoughts in response, including what this is going to mean for upcoming releases...

It's worth recognising that Wagtail, as a project with a significant user-facing component, is in a different place to a purely developer-centric library when it comes to what's considered a breaking change. If the user interface changes to the point that an organisation has to update their training materials - or, simply, users have to adjust to new conventions - then that's a disruptive change just as much as changing an API in the code would be, and the version numbering should reflect that.

Secondly, I think it's important to note that semantic versioning isn't going to be a foolproof indicator of how 'safe' it is to upgrade, particularly for add-on packages. It's fairly common for packages to make use of undocumented Wagtail internals, knowingly or not - hopefully this will become less of an issue over time as we expand the scope of "Wagtail as a platform" and offer more formal extension APIs for the kind of things that packages want to do, but it won't go away entirely. An example would be the stream_data property of StreamField, which was used widely by third-party code but was never an official API. In this case, we were aware of the potential for disruption, and put it through our standard two-release deprecation process, as we would when deprecating an official API, but it's easy to see a scenario where a change we thought was internal-only ends up having an impact on third-party code. In our new SemVer world, it's likely that those kinds of changes will still happen in minor releases - that's the only reasonable middle ground between constantly releasing major versions every time there's the slightest possibility of a breaking change, and feeling too paralysed to make any substantial changes in minor releases at all.

As for what this means for the immediate future: the current roadmap for the page editor redevelopment project is that the May 2022 release will have the major visual refresh, with the August 2022 release having the data model changes (which I envisage being somewhat larger than the 2.15 telepath update) to support things like auto-saving. Given the above thoughts on versioning, this will put us in the slightly odd situation of releasing Wagtail 3.0 and 4.0 in close succession. As I see it, though, embracing that oddness is part of the deal of adopting SemVer :-) - setting version numbers according to the engineering considerations, rather than basing it on marketing or the psychological factor of "we've just completed a big feature, let's bump the version number to celebrate". And really, the alternatives seem equally weird - such as releasing a 2.17 that looks radically different, followed by a 3.0 with no obvious visual differences...

As it happens, there are some other notable breaking changes poised to drop within the next couple of months, such as the core module reorganisation and removing the hallo.js editor, so a 3.0 release in May will be justified either way.

On the subject of LTS releases - my feeling is that they should continue to happen once a year regardless of where that might land in the numbering sequence, since the whole point of LTS is to provide a predictable timeline for support, whereas SemVer will make the timings of major version bumps inherently unpredictable. I might have second thoughts about that when we start putting it into practice, though - it may turn out that aligning them makes logical sense (e.g. making an LTS for the last version before we drop Django 3.2 support).

[vsalvino]

Excellent reasoning; I wholeheartedly agree. Doing LTS for the last minor version before the next major version, a la Django, makes a lot of sense as well, as most folks can "safely" be stuck on 2.x for a while until everything supports 3.0, and so forth (which you know will happen regardless whether its safe or not)

Thank you Matt!