Versioning & Release Practices

Last modified by Simon Urli on 2024/03/19 14:07

Version Names

  • LTS Release: This is the most stable version and is what we recommend to use in production.
  • Stable Release: This is the version recommended if you wish to try out the new features from the current Cycle (see below for an explanation of what a Cycle is). It's possible to use those in production .
  • Unstable Release: This is the version to use if you want to test the really latest feature and provide feedback to the XWiki development team and help us stabilize the version. We don't recommend that you use these in production.

Version Types

General format: Major.Minor.Bugfix[-rc-number|-SNAPSHOT]

The Bugfix part is always specified, even when the value is 0 (for a minor release).

XWiki <16.0.0 The Bugfix part used to be indicated only when not 0.


  • XWiki 2.4.2: Bugfix release
  • XWiki 16.0.0-rc-1: Release Candidate release
  • XWiki 16.0.0-SNAPSHOT: Snapshot version


  • Major Releases (2.x, 3.x): Start of a new Development Cycle. Can contain non-backward compatible changes compared with the previous Cycle.
  • Minor Releases (x.5.0, x.6.0): Mostly backward compatible from the user perspective. Can introduce new features provided they don't introduce non backward compatible changes from a user perspective. From time to time we allow some non backward compatible API changes too, following our deprecation strategy. It's recommended for users to upgrade and follow minor releases since this it's much easier to regularly upgrade than done a large upgrade spanning several minors. Should check Release Notes in case some non-backward compatible changes are introduced (on the API side).
  • Bugfix Releases (x.y.1, x.y.2): Contains only bug fixes and is 100% backward compatible. It's always recommended to upgrade as soon as possible since the bug fixes can contain security fixes.
  • Release Candidate Releases (a.k.a RC Releases, x.y.0-rc-1, x.y.0-rc-2)): Candidates for the Minor releases. We usually have 1 before the final Minor release. A RC means that we consider the version to be releasable as a Minor version but we want a last round of testing from the community and users before we perform the Minor release.
  • Snapshot Releases (continuous x.y.z-SNAPSHOT, or timestamped x.y.z-20110131.125707-122, or revision numbered x.y.z-SNAPSHOT.34017): Snapshots builds happen every time there's a code commit and are performed by our Continuous Integration tool. It's not recommended to use these, and especially not in production. However, these releases are useful to verify for example that a bugfix is valid or to test some newly introduced feature and provide feedback for it. We are always in need of feedback and thus would like to have the maximum number of users try out our snapshots builds and let us now how they perform. Users can, of course, build their own version from the source.

Release Cycles and Release Strategy

Since a drawing is worth a thousand words here's our release cycle strategy (you have full textual information and details after the diagram):


  • We have a notion of Release Cycles which corresponds to Major Releases
  • A release cycle means all the release of the type N.X where N is the major and represent the cycle (and 0 <= X <= 10)
  • Duration: 11 minor releases (e.g. N.0 till N.10), one each month, from January to November.
  • The last month of the year, December sees 2 bug fix releases, to stabilize the cycle: N.10.1 and N.10.2. The releases are supposed to contain mostly bug fixes.
    • Note that the N.10.2 release can happen on the first days of January to account for end of year holidays but it should not go beyond the 3rd of January.
    • Work for N+1.0 starts once N.10.2 has been released.
  • When N.10.2 is released we announce it:
    • Post on the user forum, mentioning that the cycle is over and encourage users to start using N.10.2
    • In that post, explain all the major features that were implemented during that release cycle (make a special Release Notes for a Cycle)
  • We announce the new LTS (N.10.2) once N.10.2 is released. The following steps are executed:
    • Update the download page to have a single version (the LTS)
    • Update API pages: Platform API and Rendering API
    • Make sure that N.10.2 is announced as the LTS in the blog post for the N.10.2 release
    • Change the Debian LTS repository to point to N.10.2 by editing the script and pulling it on
    • Update the official Docker XWiki image to change the lts tags to point to N.10.2
      • Remove the lts tags from the previous LTS version and move them to the new LTS version
      • Keep the stable tags in the new LTS version until we release N+1.0
      • Keep the previous LTS version definitions until we release N+1.0
    • Check if there are important issues to release in the previous LTS branch and schedule a last release if need be
    • Create a JIRA task for adding an automatic upgrade test from the new LTS (in xwiki-platfrom-distribution-flavor-test-upgrade)
  • For minor releases we have the following release strategy (1 month total):
    • a 3 weeks release cycles till the RC
    • a 1 week release cycles till the final versions

The rationale for doing Major Releases:

  • It's a way to mark progress to the outside world and to be able to do open source marketing
  • It's a milestone in the project's life and it feels good to do it. It makes us developers feel proud of our achievements too.
  • It allows us to move forward since it's a good time to think back about what the xwiki project is and where it wants to go

We're doing monthly releases for the following reasons:

  • Be able to stabilize our CI builds faster (reduce release time means less changes which means less stabilization required)
  • Be able to get our changes faster to our users. Importantly, bugfixes are released faster to users. Note: it’s not because we release faster that our users have to upgrade as fast. They can skip some versions if they want/need.
  • Be able to get more feedback more quickly from users. Users are testing only final versions. They’re not testing milestones or RCs. Thus with more final releases we should find out about problems (if any) faster and be able to get them to our users faster. We can do this now because we have better upgrade tools (with the Distribution Wizard), making it simpler than before to upgrade an XWiki instance.
  • Get closer to cloud needs. Nowadays, could offerings happen more and more and operating a cloud means bringing improvements and fixes as fast as possible. Some software in the cloud are even updated/patched several times per day. We’re not there yet but we’re trying to get closer by reducing from 3 months to 1 month (we used to release the minor versions every 3 months).
  • This also means more marketing for the xwiki project since other sites relay the news whenever a final version is released emoticon_smile

Release quality

All releases are as stable as possible. It is very unlikely that something will "blow up" in a new release, as the Continuous Integration setup assures that at almost any point XWiki is stable. Even snapshot builds, although not as thoroughly tested and not as polished as official releases, are most of the times stable. The short timespan dedicated to each version also imposes that no major code changes can occur during the development phase, so although some parts are "in development" between releases, most of the code should behave identically to the previous release.

The bugfix releases rarely solve critical bugs in their equivalent minor release, they usually backport bugs solved during the future release. These bugs aren't blockers, just things that need to be ironed out, so instead of waiting for the x.y.z release, better try the most recent minor release, since it is almost as stable, but with even more bugs fixed and some new features.

Releases and SCM

We use Git and follow these rules:

  • master is our latest work, i.e. what will be the next release (you can check the Roadmap for it)
  • We have a few stable branches (named using the pattern stable-<version>.x (e.g. stable-4.1.x) which are bugfix branches for past releases. When an important bug gets fixed on master it's usually backported on those branches so that they get it when they're released (we don't have any Roadmap for bugfix branches - We just do them either when a critical bug is found, when people ask for it or when we consider there are enough fixes on them).
  • All releases have tags too (e.g. xwiki-commons-4.1.3 in the XWiki Commons git repository)
  • Developers are allowed to create feature branches when they work on experimental stuff that is not yet ready to be committed on master. The plan is that they merge it later on on master when it's ready and remove the feature branch

Get Connected