== Current situation ==
- Currently our versions such as `wmde11` are just a suffix to the mediawiki version they are built on
- Users don't get any "meta info" based on the current numbering
- The current versioning scheme does NOT
- Communicate breaking changes
- Allow updating on a stable channel to get security fixes but prevent breaking changes
- Provide an obvious way to communicate security fixes in dependencies while the MW version stays the same
- Allow naming of cutting edge builds off of the upstream main branches (T343692)
== Ideal situation ==
- We want to focus on how users see the versioning scheme
- They need to be able to distinguish major versions from minor versions
- They need to see whether a version includes breaking changes or not
- They need to be able to follow patches while staying on a stable version without breaking changes
- It should be easy to auto update following certain rules, such as "always run latest" or "stay on 3.x"
- Building using a certain version of the pipeline should create the same build artifacts (T340226) which get a unique versions assigned to them
== Research ==
The built artifacts consist of components from loads of different sources with different versioning strategies:
|Component|Explicit versioning|Communication of breaking changes|Link|Notes|Interface to the user|Bumps version|
|---|---|---|---|---|---|---|
|MediaWiki|yes (e.g. 1.39.4), but not semver, going from 1.39 to 1.40 contains breaking changes|yes, in changelog|[Changelog](https://gerrit.wikimedia.org/g/mediawiki/core/%2B/HEAD/HISTORY)|We might want to add unreleased security patches to our builds T341450|**UI**, **API**, DB, LocalSettings, Plugins, Skins|yes, minor MW version will trigger major Suite version bump, MW patch version will trigger Suite patch version, as stable MW versions only receive fixes (mostly)|
|MediaWiki Docker image|no, version only represents the MW version built in, not the underlaying tools such as apache (from debian base image) or php (from php base image)|no|https://hub.docker.com/_/mediawiki/|Released by a volunteer https://github.com/wikimedia/mediawiki-docker https://phabricator.wikimedia.org/project/view/6633/, apparently looking for support T330367. **TODO:** Should we build our own to be independent?|Same as above|Same as above, but can also trigger Suite patch version bump on rebuild (debian stable updates)|
|PHP Docker image (base for official MediaWiki Docker image)|yes, but only PHP version, apparently does not get updated when the underlaying debian gets updates, as older php version images are only pushed a long time ago|yes, through PHP version|https://hub.docker.com/_/php|**TODO:** Should we just build our own to reduce moving parts and 3rd party dependencies? | PHP version and config for custom extensions |**TODO** probably just bumps suite patch version|
|Debian Docker image (base for official PHP Docker image)|yes, Debian versioning, but not semver, a datetime string getting updated on security patches|yes, with major release|https://hub.docker.com/_/debian| | (https.conf) |debian minor versions just bump suite patch versions, switch debian major release only with suite major releases|
|Wikibase|no, ensures MW compatibility on REL branches|**TODO** RESEARCH| [Release notes](https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/extensions/Wikibase/+/refs/heads/master/RELEASE-NOTES-1.40) | should receive security patches as long as the related MW version is supported!? We might want to add unreleased security patches to our builds T341450 | **UI**, **API** | **TODO** |
|other WMF hosted extensions, e.g. CirrusSearch|no, ensure MW compatibility on REL branches|**TODO** RESEARCH| [Extension Page](https://www.mediawiki.org/wiki/Extension:CirrusSearch) | should receive security patches as long as the related MW version is supported!? We might want to add unreleased security patches to our builds T341450 | **TODO** | Should just receive security fixes on the REL branches, so changes there only bump Suite patch version |
|other extensions from e.g. GitHub|arbitrary versioning strategies, sometimes just a main branch| | | | **TODO** | This is complicated to monitor, we need to evaluate every change in every extension and decide wether this is breaking or not, breaking changes need to be held back from stable releases, security fixes need to go into stable releases, we might even end up forking the extension to maintain an lts version with all the latest fixes. OR: we just do not officially support those extensions.|
|MariaDB Docker image|yes, following mariadb version|probably through mariadb version, **TODO** RESEARCH|https://hub.docker.com/_/mariadb|might need updates as soon as base libs get updates| **on-disk files**, (my.conf) | the database is an interface to the user, binary on-disk data incompatibility (is this a thing in maria? probably not) should trigger major version bump, otherwise patch version bumps |
|WQS release|yes, 0.y.z|**TODO** RESEARCH| |we build it into an openjdk docker image which is needs updates as well, NB, the one we are using is deprecated and the tag we are using received the last update 4 years ago, so probably in 2019 (T345425)| **TODO** | **TODO** |
|WQS frontend|no, master branch|||built into an docker hub official nginx image, needs nginx and base system patches| **TODO** | **TODO** |
|QuickStatements|no, master branch||| based on php image, see above| **TODO** | **TODO** |
|MagnusTools|no, master branch|||used in the QuickStatements container| **TODO** | **TODO** |
|anything missing?| | | | | | |
== Suggestion - Request For Comments ==
=== Versioning Scheme ===
We use SemVer (Semantic Versioning) https://semver.org/
- Breaking changes increment major version e.g. 2.3.1->3.0.0
- Feature releases increment minor version, e.g. 2.0.4->2.1.0
- Fixes, e.g. security fixes increment patch version, e.g. 2.0.0->2.0.1
- Pre-releases can be marked with an additional suffix following a hyphen (-), e.g. 3.0.0-alpha.20230411
We start with a major version of 2.0.0 (so this is bigger than current 1.39 mw version based releases).
=== What to version ===
We version the built artifacts, not the pipeline code. The pipeline code has a rolling release `main` branch. We use tags on the pipeline `main` branch to note which version of the pipeline builds which wikibase suite releases (see below).
All built artifacts of one version are together considered one wikibase suite release, that is:
- Container images for MediaWiki+WikiBase+Extensions aka Bundle, WDQS, WDQS Frontend, etc.
- docker-compose files defining the whole stack ready to run
- env files configuring the whole stack ready to run (sane defaults, **TODO: but what about passwords and keys?**)
- see T340234 for more information
=== Versions maintained in channels ===
There are three version channels maintained at every time: "stable", "oldstable" and "next".
- "stable", contains the current stable version, should be based on latest mediawiki stable most of the time
- "oldstable", contains the last stable version (was in stable channel before), still receives fixes
- alternative approach: "lts", contains the current mediawiki lts release and all the other components maintained "as stable as possible" (mediawiki lts is maintained for 3 years https://www.mediawiki.org/wiki/Version_lifecycle) **TODO: decision**
- "next", contains the unstable version created off of the main branches of upstream components, contains mediawiki stable right after mediawiki release, until we are ready to release it as stable
The "next" builds allow us to be ready to release the next stable version soon after mediawiki releases the next stable version.
- Example at a certain point in time:
- "stable" has 3.6.2, the current version, based on MW 1.40.4
- "oldstable" has 2.8.1, the old version, based on MW 1.39.6
- "next" has 4.0.0-pre20230528, the upcoming unreleased version, based on MW main (**TODO**: we cannot use the date, can we? Can we build without updating the build code?)
Stable releases do not include any breaking changes for the user. We support them for a while (**TODO**: define how long). Breaking changes can happen at any time to the version currently in the "next" channel.
=== Bumping stable version ===
At a certain point in time we decide that the version in "next" channel is stable enough to become "stable". (**TODO**: how do we decide that?)
The process is the following:
Before the version bump we have e.g.:
- "oldstable" has 2.8.1 the old/LTS version
- "stable" has 3.6.2 the current version
- "next" has 4.0.0-pre20230528 the upcoming unreleased version
Bumping the version means:
- the version from "oldstable" does not receive any updates anymore, that is 2.8.1 is the last 2.X version in the example
- the version from "stable" becomes "oldstable", so the "oldstable" channel will from now on point to 3.X
- the version from "next" becomes "stable", so stable will point to the first version of 4.X, which is 4.0.0
- "next" will follow "stable"
- when the next breaking change comes in, "next" branches off of stable and gets a new version number 5.0.0-preBUILDDATE
=== Tagging the pipeline main branch ===
In order to document, which version of the pipeline can build which wikibase suite versions, we use git tags on the `main` branch. Example: A single version f82a7cff of the `main` branch has the following three tags
- v2.8.1 the latest release of the old/LTS version (oldstable channel)
- v3.6.2 the latest release of the current version (stable channel)
- v4.0.0-pre20230528 the latest build of the upcoming unreleased version (next channel) (**TODO**: we cannot use the date, can we? Can we build without updating the build code?)
This is because this single pipeline version can build all latest versions from all supported channels ("stable", "oldstable", "next") at the same time.
=== Distribution ===
The wikibase suite distribution consists of two kinds of things. A set of files and a set of docker images. The files will be distributed as a git repo. The docker images will be distributed via a docker registry.
All docker images are tagged with the version and the channel name of the version they are created for. Lets take the example from above again. Each of the docker images belonging to the release will be tagged as follows:
For "oldstable" 2.8.1 the old/LTS version, all images will have the following tags:
- "2.8.1" to have a tag for the full version number, the indivitual image identifying tag that never changes
- "2.8" to have a tag that will be reused for patch versions of the same minor version
- "2" to have a tag that will be reused for minor versions of the same major version
- "oldstable" to have a tag that follows the channel and is reused as soon as the channel updates
For "stable" 3.0.0 the current version, all images will have: "3.6.2", "3.6", "3" and "stable". It is the same pattern as for "oldstable".
For "next" 4.0.0-pre20230528 the upcoming unreleased version, all images will have the following tags:
- "4.0.0-pre20230528" to have a tag for the full version number, the individual image identifying tag that never changes
- "4" to have a tag that will be reused for this major version
- "next" to have a tag that follows the channel and is reused as soon as the channel updates
**TODO**: how do we version the files relating to the release? Probably in the same scheme, just using git tags and branches