Wiki source code of Versioning & Release Practices

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

Hide last authors
Vincent Massol 3.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
Vincent Massol 8.1 5 = Version Names =
6
7 * **LTS** Release: This is the most stable version and is what we recommend to use in production.
8 * **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 .
9 * **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.
10
Vincent Massol 2.1 11 = Version Types =
12
Thomas Mortagne 26.1 13 General format: ##Major.Minor.Bugfix[-rc-number|-SNAPSHOT]##
Vincent Massol 2.1 14
Vincent Massol 28.1 15 The Bugfix part is always specified, even when the value is 0 (for a minor release).
16
Thomas Mortagne 26.1 17 {{version before="16.0.0"}}
18 The ##Bugfix## part used to be indicated only when not 0.
19 {{/version}}
20
Vincent Massol 2.1 21 Examples:
22
Ecaterina Moraru (Valica) 9.1 23 * XWiki 2.4.2: Bugfix release
Thomas Mortagne 26.1 24 * XWiki 16.0.0-rc-1: Release Candidate release
25 * XWiki 16.0.0-SNAPSHOT: Snapshot version
Ecaterina Moraru (Valica) 9.1 26
Vincent Massol 2.1 27 Explanations:
Ecaterina Moraru (Valica) 9.1 28
Thomas Mortagne 26.1 29 * **Major** Releases (**2**.x, **3**.x): Start of a new [[Development Cycle>>#HReleaseCyclesandReleaseStrategy]]. Can contain non-backward compatible changes compared with the previous Cycle.
30 * **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>>DevelopmentPractices#HDeprecationRules]]. 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).
Sergiu Dumitriu 4.1 31 * **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.
Thomas Mortagne 26.1 32 * **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.
33 * **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>>ContinuousBuild]]. 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>>Building]] their own version from [[the source>>SourceRepository]].
Vincent Massol 2.1 34
Vincent Massol 1.1 35 = Release Cycles and Release Strategy =
36
Vincent Massol 11.1 37 Since a drawing is worth a thousand words here's our release cycle strategy (you have full textual information and details after the diagram):
38
39 {{image reference="releasecycle.png"/}}
40
Vincent Massol 15.1 41 * We have a notion of **Release Cycles** which corresponds to Major Releases
42 * 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)
43 * Duration: 11 minor releases (e.g. N.0 till N.10), one each month, from January to November.
Simon Urli 27.1 44 * 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.
Vincent Massol 15.1 45 ** 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.
46 ** Work for N+1.0 starts once N.10.2 has been released.
47 * When N.10.2 is released we announce it:
Vincent Massol 25.1 48 ** Post on the user forum, mentioning that the cycle is over and encourage users to start using N.10.2
49 ** In that post, explain all the major features that were implemented during that release cycle (make a special Release Notes for a Cycle)
Vincent Massol 22.1 50 * We announce the new LTS (N.10.2) once N.10.2 is released. The following steps are executed:
51 ** Update [[the download page>>xwiki:Download.WebHome]] to have a single version (the LTS)
Simon Urli 25.2 52 ** Update API pages: [[Platform API>>xwiki:Documentation.DevGuide.API]] and [[Rendering API>>rendering:Main.JavaDoc]]
Vincent Massol 22.2 53 ** Make sure that N.10.2 is announced as the LTS in the blog post for the N.10.2 release
Simon Urli 29.2 54 ** Change the Debian LTS repository to point to N.10.2 by editing the [[scan_packages.sh script>>https://github.com/xwiki/xwiki-dev-tools/blob/master/debian/xwiki_scanpackages.sh]] and pulling it on maven.xwiki.org.
Vincent Massol 24.1 55 ** Update the [[official Docker XWiki image>>https://github.com/docker-library/official-images/blob/master/library/xwiki]] to change the ##lts## tags to point to N.10.2
56 *** Remove the ##lts## tags from the previous LTS version and move them to the new LTS version
57 *** Keep the ##stable## tags in the new LTS version until we release N+1.0
58 *** Keep the previous LTS version definitions until we release N+1.0
Vincent Massol 22.1 59 ** Check if there are important issues to release in the previous LTS branch and schedule a last release if need be
Simon Urli 27.1 60 ** Create a JIRA task for adding an automatic upgrade test from the new LTS (in ##xwiki-platfrom-distribution-flavor-test-upgrade##)
Vincent Massol 15.1 61
62 * For minor releases we have the following release strategy (1 month total):
63 ** a 3 weeks release cycles till the RC
64 ** a 1 week release cycles till the final versions
65
Vincent Massol 1.1 66 {{info}}
67 The rationale for doing Major Releases:
Simon Urli 27.1 68
Vincent Massol 1.1 69 * It's a way to mark progress to the outside world and to be able to do open source marketing
70 * 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.
71 * 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
72 {{/info}}
73
Vincent Massol 8.2 74 We're doing monthly releases for the following reasons:
Ecaterina Moraru (Valica) 9.1 75
Vincent Massol 8.2 76 * Be able to stabilize our CI builds faster (reduce release time means less changes which means less stabilization required)
77 * 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.
78 * 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.
79 * 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).
80 * This also means more marketing for the xwiki project since other sites relay the news whenever a final version is released :)
Vincent Massol 1.1 81
Sergiu Dumitriu 5.1 82 = Release quality =
83
84 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.
85
Vincent Massol 15.1 86 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.
Sergiu Dumitriu 5.1 87
Ecaterina Moraru (Valica) 9.1 88 = Releases and SCM =
Vincent Massol 6.1 89
90 We use Git and follow these rules:
Ecaterina Moraru (Valica) 9.1 91
Manuel Smeria 7.2 92 * ##master## is our latest work, i.e. what will be the next release (you can check the [[Roadmap>>xwiki:Roadmaps.WebHome]] for it)
Vincent Massol 8.2 93 * 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).
Vincent Massol 6.1 94 * All releases have tags too (e.g. ##xwiki-commons-4.1.3## in the XWiki Commons git repository)
95 * 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