New GNOME versioning scheme

Hi all;

after various off-line/in person talks, last year I started a discussion on Discourse about the existing version scheme of GNOME. This topic was also raised in July, and discussed at the release team meeting during GUADEC. Now that the GNOME 3.37 development cycle is over, and 3.38 is out of the door, it’s time to draw this issue to its conclusion.

In the interest of clarity, I’ll present the conclusion first, and then try to answer common questions. The questions summarise the feedback and iterations of the change; feel free to read the whole topic on Discourse if you wish to understand what led to the final form of this change.

The new GNOME versioning scheme

The next version of GNOME, due to be released in March 2021, will be GNOME 40.

The GNOME 40 development cycle will have three releases:

  • 40.alpha
  • 40.beta
  • 40.rc

Followed by the first stable release, 40.0. Every subsequent stable release will increment the minor component by 1, so:

  • 40.1, 40.2, 40.3, …

After the 40.0 release in March 2021, the next version of GNOME will be 41, and will follow the exact same pattern.

To recap:

  • the new versioning scheme starts at 40
  • each new development cycle will increment the version by 1
  • each development cycle will have three releases: alpha, beta, rc (release candidate)
  • the first stable release will have a minor version of 0
  • each stable release will increment the minor version by 1

Adopting the new versioning scheme

The new version will be visible in the following components:

  • the “GNOME version” field of the “About” section in GNOME Control Center
  • the version of GNOME in the Tour application
  • the application version in the “About” dialog of core GNOME applications

Additionally, the version of the SDK and Platform run times will follow the same versioning scheme, so you will depend on, for instance, org.gnome.Platform//40.

If you maintain an application that is not in the list above, then you can keep following your own versioning scheme.

Libraries in the platform are not expected to change their existing versioning scheme, but they are still expected to follow the release cadence of GNOME, with at least an alpha, beta, and rc releases.

If your GNOME core application provides an API—for instance, for plugins—you can version the programming interface however you prefer, as long as the user visible version of the application follows the GNOME scheme.

Frequently Asked Questions

Q: Why do we need a new versioning scheme?
A: After nearly 10 years of 3.x releases, the minor version number is getting unwieldy. It is also exceedingly clear that we’re not going to bump the major version because of technological changes in the core platform, like we did for GNOME 2 and 3, and then piling on a major UX change on top of that. Radical technological and design changes are too disruptive for maintainers, users, and developers; we have become pretty good at iterating design and technologies, to the point that the current GNOME platform, UI, and UX are fairly different from what was released with GNOME 3.0, while still following the same design tenets.

Q: Why start at 40?
A: Because the next version would be 3.40, and it’s a nice, round number. The 3.38 release was the 40th release of GNOME, but this discussion came too late in the cycle to effectively switch, so we can say that, if you start counting at zero, the next cycle would be the 40th release of GNOME. By using 40 as the base, we acknowledge what came before, and we don’t introduce a large discontinuity in the number progression, which is somewhat the point of this change.

Q: Why not 4.0?
A: With GTK 4.0 being released during the next development cycle, calling the next version of GNOME “4.0” would have unfortunate/unintended implications about the platform, especially from an engagement and marketing perspective. We want to decouple GNOME from deep changes in the application development platform, so that GTK can be released more often, and provide “long term support” major versions, instead of delaying development cycles that inevitably end up into “rewrite the world” events. GNOME is not just a technological platform, but also a set of design guidelines and an ethos, and bumping the major version along with GTK does not reflect that.

Q: Why not using the year/month scheme?
A: While date-based versioning schemes do make it easier to resolve the issues of “when was this version of GNOME released” and “how old is my version of GNOME compared to the latest one”, they still rely on knowing that the version number is, indeed, date based. Even the “gold standard” of date-based releases, Ubuntu, has users confused about the version numbers, as outlined in multiple topics on different user support forums. Additionally, a date-based versioning scheme on the twice-per-year schedule we have, with stable releases that continue over the span of a year each, introduces possible collisions and uncertainty, unless more numeric components are added, thus making version numbers longer and more complicated.

Q: What happened to even/odd (or “Linux kernel style”) versions?
A: Just like the Linux kernel, we found that there’s no real advantage in an even/odd split any more. Not many people actually use the odd-numbered versions of GNOME, even when distributions package them. From the perspective of application developers, especially with the advent of bundling technologies like Flatpak, you will either use the bleeding edge “nightly” snapshots, or, more likely, you’ll use the current stable run times until you are ready to update them.

Q: What about semantic versioning/semver?
A: Individual components of the GNOME software development platform—like GLib or GTK—typically follow semver rules. For a project made of other projects, like GNOME, it’s less useful to do so because semver doesn’t tell you anything about the contents of the project; it doesn’t tell you that an application shipped with GNOME added a command line argument, or that there’s a new feature, or that a button has a new label. It doesn’t tell you that there have been bug fixes, or that they resulted in changes in the documentation or in the user visible strings. Unless, of course:

  • GNOME bumped the micro version if a single component did a bug fix
  • GNOME bumped the minor version if a single component added a new feature
  • GNOME bumped the major version if a single component removed or changed an existing UI element

which would be fairly ridiculous, and lead to even more major releases.

Q: Why only three development releases?
A: With the advent of nightly builds and continuous integration and delivery pipelines, there’s no real advantage in having multiple alpha and beta snapshots any more, considering the amount of people actually using them outside of GNOME maintainers (and the odd packager); they are mostly busy work for the release team, at this point. Maintainers do tend to skip the alpha releases, and having more releases in the beta/release candidate period usually injects more stress into the development process. Nevertheless, if maintainers wish to do multiple releases, they are absolutely free to do so. The release team will guarantee those three development releases for the whole of GNOME.

Q: Does this versioning scheme apply to every GNOME project?
A: The intended audience for this versioning scheme is GNOME users. Libraries have difference constraints, and thus do not need to conform to it, and neither do applications that are not in the core applications set, as defined by the release team. Maintainers are free to follow the same scheme, or adopt their own. Some applications expose a programmable interface for out of tree plugins; the interface can have its own versioning scheme, or it can follow the version of the application.

Q: What about packaging development releases of GNOME? How do we deal with the new versions?
A: Since packaging rules vary from distribution to distribution, and from packaging format to packaging format, it is left to the downstream packagers’s judgement how to translate the “dot-alpha”, “dot-beta”, and “dot-rc” versions into something that can be appropriately represented by their downstream project. If the packaging rules or format do not allow alphabetic components, or do not sort alphabetic components before numeric ones, we recommend using something like:

  • .0alpha, .0beta, .0rc
  • .0~alpha, .0~beta, .0~rc
  • .0a, .0b, .0rc

which should sort in the correct order, and do so before the .0, .1, … of the stable releases.

Q: How does this scheme impact the branch naming when opening a new development cycle?
A: The stable branches will keep the same policy, “gnome-” + version; so you will have “gnome-40”, “gnome-41”, and so on, and so forth.

Q: What version number should I use between the latest stable release and the new development cycle?
A: You should use the version of the next stable, plus the “alpha” component. Once you cut the alpha release, you update to “beta”; once you cut the beta release, you update to “rc”; once you cut the release candidate, you update to 0.

Q: Can I make additional alpha/beta/rc releases? How do I call them?
A: Of course you can do more releases, if you want to; you can use a scheme such as:

  • .alpha.0, alpha.1, …
  • .beta.0, beta.1, …
  • .rc.0, .rc.1, …

to distinguish them.

Q: I do pre-release version bumps; what do I do, now?
A: The preferred model is to move to post-release version bumps. In other words: you change the version of your project after cutting a release. For instance, a typical development cycle might look like this:

  • you just released “40.0” (first stable release)
    • open the development cycle for GNOME 41
    • create the gnome-40 branch
    • bump the version of your project to “41.alpha” in your development branch
    • commit the change
  • hack, hack, hack
  • release “41.alpha”
    • update the NEWS file
    • commit the change
    • tag the commit
  • bump the version of your project to “41.beta”
  • commit the change
  • hack, hack, hack
  • release “41.beta”
    • update the NEWS file
    • commit the change
    • tag the commit
  • bump the version of your project to “41.rc”
  • commit the change
  • we are in freeze, so hack with caution
  • release “41.rc”
    • update the NEWS file
    • commit the change
    • tag the commit
  • we are now in hard code freeze, so no hacking
  • release “41.0”

This is a change that might take a bit of an adjustment, but we feel it’s the best compromise towards a consistent versioning behavior.

Q: This is nonsensical. Why do you want to change the versioning scheme at all? It’s just numbers!
A: Numbers, like words, have meaning, and tell a story. With a change in the versioning scheme we wish to communicate the fact that GNOME doesn’t see major versions of the development platform as the driving force behind major changes in its user experience; and that radical changes to the user experience are going to be introduced progressively, so that we can refine and iterate over them in time, instead of dumping them in our users lap.

Additional questions

Feel free to discuss this topic on Discourse, and to reach out to the release team for additional clarifications.

On behalf of the GNOME release team,
Emmanuele Bassi

17 Likes

Can this be stricter? Meaning, use “MUST” instead of “can”. It’s way easier if the whole thing is standardized, plus that e.g. things like ftpadmin checks if the version number follows that standard.

Because possibly a manager could call an alpha1 either 40.alpha, 40.alpha1, 40.alpha.1 or perhaps even something else. Furher, there currently are multiple alpha versions, no?

Currently the announcement makes it appear that there will be less releases, not sure if that’s the case or not. If I use the 3.37/3.38 as example wouldn’t we have something like the following?

3.37.1 → 40.alpha.1
3.37.2 → 40.alpha.2
3.37.3 → 40.alpha.3
3.37.90 → 40.beta.1
3.37.91 → 40.beta.2
3.37.92 → 40.rc / 40.rc.1 ?
3.38.0 → 40.0

I assume those version numbers will be put on the new ThreePointThirtyseven - GNOME Wiki!, right?

1 Like

Yes, there will be fewer development releases of GNOME.

Compared to the old scheme, we’re going to have:

  • Alpha phase
    • 3.39.1
    • 3.39.2
    • 3.39.3 → 40.alpha
  • Beta phase
    • 3.39.90
    • 3.39.91 → 40.beta
  • Release candidate phase
    • 3.39.92 → 40.rc
  • Stable
    • 3.40.0 → 40.0
    • 3.40.1 → 40.1
    • 3.40.2 → 40.2

If application maintainers decide to spin up additional alpha, beta, or release candidate releases, they can. Just like we might have had versions like 3.39.90.1 or 3.39.92.1, the maintainers can spin 40.beta.1 and 40.rc.2.

Yes, the schedule will be updated accordingly. With fewer development releases we’re going to decide when to make them—whether to match the first alpha/beta releases in the old scheme, or match the last alpha/beta releases.

1 Like

This is nice. I like it.

Now a cautionary tale. When Tracker 2.0 was released and we switched to semantic versioning there, we picked a much similar alpha/beta versioning scheme for pre-release tarballs.

This all went alright until the next time we made an alpha release. This broke ftpadmin and required @averi to place the tarball manually, and it was all trouble further down the line. Everything broke, from FTP announcement scripts, to release-team ones. In the end @mcatanzaro yanked the tarball from FTP. Even though Tracker still does semver, we’ve since contented ourselves with purely numeric versions.

I didn’t check if this release proposal came together with sysadmin/r-t work to make sure the whole release pipeline can withstand the new versioning scheme, but that was very much not the case. Could be nice to check early and save some chaos in the first releases.

Yes, it’s been raised. Fixing the ftpadmin script is in the works.

Edited, to add: Update version check for ftpadmin (!11) · Merge requests · Infrastructure / sysadmin-bin · GitLab

1 Like

A post was split to a new topic: Consolidate all about dialogs for core components into a single credits page

Personally I dislike the change but I suppose since it was announced
already, it is set in stone, so no point trying to convince of retaining
the status quo there. What I actually think would have been best is
to keep the gtk-version for GNOME too. So GNOME3 would be for
gtk3; GNOME4 would be for gtk4, and so forth. But alright.

I guess one change here is that the odd-number schemata, e. g.
for 3.37.98 and such is no longer used (since it is replaced with
the alpha, beta or rc suffix). So this may not be only bad,
considering I have had problems with the unstable branch
every now and then.

Had you read the announcement—and the topic on Discourse where the new versioning scheme was discussed for about a year—you’d have seen that the entire point is to decouple versions of GNOME from versions of GTK, to avoid “stop and rewrite the world” major development cycles that inevitably take more than 6 months.

I love the new versioning scheme! (The old 3.XX really downplayed all the changes that went into every release, and it felt like GNOME would never go higher than 3.)

Huge thanks to @ebassi for such a wonderful write-up about it that covers basically every question anyone would have.

4 Likes

I love the new versioning. What I absolutely dislike is the versioning of alpha,beta,rc. I can see that might conflict with some package management systems where
40.alpha > 40=40.0

Wouldn’t it be more sane to just go for something like
Alpha X = (n-1).97.x
Beta X = (n-1).98.x
RC X = (n-1).99.x

And stay away from potential downstream versioning conflicts in the first place?
So 40, alpha 1 would be “39.97.1”, beta 3 would be “39.98.3” and RC 15 “39.99.15

Except that part I LOVE it. :heart:

This newly-announced versioning system will be enough used, so that distributors could check their packages management system, when distributing the future release. Describing it early gives them the time to handle that. For humans, using alpha/beta/rc is clearer than 97/98/99, and I think computers could do their part to make things easy for our brains. :smiley:

1 Like

Yes, but these package management systems usually allow tildes instead, so packagers would convert it to e.g. 40~alpha. alpha/beta/rc versioning is already sufficiently common that every downstream should already have a plan to handle it.

1 Like

Emmanuele has posted this topic to the following lists:

  • gtk-app-devel-list -at- gnome org
  • distributor-list -at- gnome org
  • desktop-devel-list -at- gnome org

https://mail.gnome.org/archives/distributor-list/2020-September/msg00000.html

It would be nice to hear the distributors side of the story that way.

Thanks!

2 Likes

6 posts were split to a new topic: Similarities between GNOME and Python versioning

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.