Contains instructions to perform various release steps in the Release Plans.

Initial Backward Compatibility Check

This initial step checks if the previous release cycle, or more recent bugfix releases done since, have properly set the xwiki.compatibility.previous.version property in the top level POM of xwiki-commons (for the branch you are currently releasing).

For example, if the current release to be made is for 4.2-milestone-3 and, in the meanwhile, there have been released bugfix versions for 4.1 (4.1.4 being the latest released), you need to ensure that the value for xwiki.compatibility.previous.version is 4.1.4.

Create the release dashboard

The easiest is to copy the dashboard of the most recent previous release and then modify a few things:

• the copy will obviously still point to the copied version so you need to change the filter, click the Total link at the botton of the top right widget, for example
• modify the filter to set the right including and excluding versions: fixVersion in (17.5.0-rc-1, 17.5.0) AND fixVersion not in (17.4.1) a RC or first stable version, or just fixVersion in (17.5.1) for a bugfix version
• use Save as and indicate a name with the right version: Issues fixed in XWiki 17.5.0
• click Details -> Edit permissions and set the right permission
  • Add Viewers: Anyone on the web
  • Editors: xwiki-committers
  • Save
• Modify each widget to use the new filter

Verify JIRA issue

If there are opened JIRA issues for the version you are currently releasing (fixVersion is set to the current release), you have two options:

1. The issue has no code committed yet (Commits tab shows nothing). In this case, you need to push the issue to the next development version. (e.g. fixVersion = 6.3-milestone-1 will be moved to fixVersion = 6.3-milestone-2)
2. There is some code already committed (Commits tab is not empty). In this case, you need to contact the assigned developer of the issue and find out if the committed code is complete:
   1. If the code is complete, you can close the issue (or ask the dev to do it)
   2. If the code is not complete, you can close the issue and ask the dev to create a new issue for the remaining work to be done for the next version.

In all cases, all opened issues must be closed before the release can be done.

Verify issues with commits

Such open issues may exist because the wrong issue key was used when committing, the existing commits are just trying to fix a test or adding extra logging (and not affecting the runtime) while the problem has not been addressed, it's a commit in a feature branch, etc. You need to ignore these false positives and detect any issue that has actual work done on it that is relevant for this release, close it and assign it the correct fix version so that it's properly counted in the release notes.

Note: The JIRA query is not perfect yet as we cannot query on the commit update date. Thus FTM you'll need to review each issue listed and verify if the issue should be closed or if it's a false positive.

Log on Release machine

# Get on the maven CI master machine
me@home:~$ ssh [email protected]

# Get on the agent machine
maven@maven:~$ release

Set up your identity

The first time

• Configure your Github profile to add the SSH key of the agent so that the commits can be pushed to Github with your user (To get the agent SSH key, do cat ~/.ssh/releaser_ssh.pub). To verify it works, do the following on the agent machine: ssh -T [email protected]. It should reply with Hi <your user id>! You've successfully authenticated, but GitHub does not provide shell access..
• Create your own GPG key if you don't already have one: gpg --gen-key
• Publish your public GPG key, if you have not already done so: gpg --keyserver hkp://keys.openpgp.org --send-key <keyID>
• Register the GPG key on your GitHub account
• Import your GPG key:
  • On your local computer run: gpg --list-secret-keys
  • Export your key in a secret.key file: gpg --export-secret-keys «keyID» > secret.key where keyID is the hexadecimal string on the sec line (either 8 char long or 40 char long)
  • Copy the secret.key file to the agent machine (you may need to copy to maven.xwiki.org first and then to agent-1-1)
    • From your local computer, upload the key to maven.xwiki.org: scp secret.key [email protected]:/home/maven
    • From maven.xwiki.org (/home/maven): scp -i ~/.ssh/releaser_ssh secret.key [email protected]:/home/releaser/<yourname>.gpgkey (give it a name)
      • The key can be stored on the agent, since it's password protected, so that you don't have to upload it next time, and just re-import it.
      • TODO: find out how we can keep the keys imported and tell maven which one to use during the release.
    • Remove the key from maven.xwiki.org after you have uploaded it to agent-1-1: rm secret.key
  • On the agent machine, run gpg --import <yourname>.gpgkey
• You need to have a .gitconfig.<yourusername> file. You can do that by copying one of the existing gitconfig file
• Make sure your gitconfig file has the key signingkey in the [user] section (the value is your key id which you can get with gpg --list-secret-keys).
• Copy your .gitconfig.<yourusername> file as the main gitconfig file: cp .gitconfig.<yourusername> .gitconfig
• Add an npm token

The other times

• Configure your Github profile to add the SSH key of the agent so that the commits can be pushed to Github with your user (To get the agent SSH key, do cat ~/.ssh/releaser_ssh.pub). To verify it works, do the following on the agent machine: ssh -T [email protected]. It should reply with Hi <your user id>! You've successfully authenticated, but GitHub does not provide shell access..
• Make sure previous release manager did not left his GPG key
  gpg --delete-secret-and-public-keys $(gpg --list-secret-keys | grep ^sec -A 1 | tail -n 1 | awk '{ print $1 }')
• Import your GPG key, run gpg --import <yourname>.gpgkey
  • If you did not leave your secret key file on the agent machine, you have to re-upload it (see The first time section above).
• Copy your .gitconfig.<yourusername> file as the main gitconfig file: cp .gitconfig.<yourusername> .gitconfig
• Add an npm token

Add an npm token

• Go to the Access Tokens section of the administration - https://www.npmjs.com/settings/USERID/tokens (or click on your avatar at the top right of the UI of https://www.npmjs.com/, then select Access Tokens.
• Click on Generate New Token
• Set the Token name to "Release of XWiki x.y.z"
• Check Bypass two-factor authentication (2FA)
• In the Packages and scopes section
  • Select the Read and write permission
  • Then select Only select packages and scopes
  • In the Select packages and scopes field, select the @xwiki value
• Click on Generate Token
• Copy the generated token in the clipboard
• On the release machine, execute export NPM_TOKEN="THE TOKEN"
• Check the token with curl https://registry.npmjs.org/-/whoami -H "Authorization: Bearer ${NPM_TOKEN}"

Update Release scripts

# Update the release script
hudsonagent@vagent-1-1-dev:~$ cd xwiki-dev-tools ; git pull --rebase ; git status ; cd ..

Update Translations (deprecated)

For a release candidate, the translations were already merged (when the Pull Requests were accepted) into the master branch which you have just forked.

For a final or bugfix version, there may be translations added since the RC or the previous final/bugfix that we need to integrate. Perform the following steps:

• Move to xwiki-trunks:

  hudsonagent@vagent-1-1-dev:~$ cd releases/xwiki-trunks/

• Run the update goal of the script with your branch (e.g. stable-10.5.x):

  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ ~/xwiki-dev-tools/weblate-scripts/apply_translations.sh update stable-10.5.x

• Review the changes for anything amiss.
  • You need to go through each project (xwiki-commons, xwiki-rendering, xwiki-platform)
  • Do a git status to spot changes.
    • Do a git diff --cached and visually review modified translation keys and spot problems (like spam).
      Warning

      Be very careful when you update translations because the new ones might concern new stuff introduced in the master branch. The issue is that the translations platform does not support branches (translations are coming from master). Also make sure that when wiki pages are updated and the XAR version is increased/new fields are introduced, the document version isn't increased beyond the version supported by the released version as this might produce warnings, otherwise (see document-xml for the supported versions) - for example, in 13.10.x, the version should be 1.4 at most.

    • No need to do a git add at this point since it will be done for all projects below.
• Push / commit the translation changes on the branch of the version you are releasing (e.g. stable-10.5.x):

  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ ~/xwiki-dev-tools/weblate-scripts/apply_translations.sh push stable-10.5.x

Compute list of updated languages

Run the following command in a XWiki git repository with indicating the previous version and current version. The script will list languages that need to be added in the Release note:

releaser@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ ~/xwiki-dev-tools/xwiki-release-scripts/release-note-scripts/get_translated_languages.py 17.10.9 17.10.10

Old way to compute list of updated languages

Collect the list of updated languages to publish in the Release Notes:

• WarningMake sure to exit screen if you're using it (it's not great at handling non-ASCII characters
• cd to each repository (xwiki-commons, xwiki-rendering, xwiki-platform)
• Run the list_translation_changes.sh script to list all relevant modified translation files since the previously released final version and generate the list of modified languages (notice the usage of the --diff parameter to help you decide if a translation language should be counted or not, see below for more details):
• WarningBe aware that since we're supporting different branches in Weblate, a branch argument is now needed. Most of the time it should be set to master except when releasing a LTS bug fix: in such case the branch should use the name of the LTS branch (e.g. stable-17.4.x).

• ## list_translation_changes.sh start_commit end_commit [options]
  
  ## Example when releasing a final version (e.g. 10.7):
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ ~/xwiki-dev-tools/weblate-scripts/list_translation_changes.sh master xwiki-commons-10.6.1 stable-10.7.x --diff | less -r
  ## Example when releasing a RC version (e.g. 10.7RC1):
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ ~/xwiki-dev-tools/weblate-scripts/list_translation_changes.sh master xwiki-commons-10.6.1 xwiki-commons-10.7-rc-1 --diff | less -r
  ## Example when releasing a LTS bug fix version (e.g. 16.10.4):
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ ~/xwiki-dev-tools/weblate-scripts/list_translation_changes.sh stable-16.10.x xwiki-commons-16.10.3 xwiki-commons-16.10.4 --diff | less -r
  
  ## Other examples on some already released versions (in case the need arises):
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-rendering$ ~/xwiki-dev-tools/weblate-scripts/list_translation_changes.sh master xwiki-rendering-10.3 xwiki-rendering-10.4 --diff | less -r
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-platform$ ~/xwiki-dev-tools/weblate-scripts/list_translation_changes.sh master xwiki-platform-10.3 xwiki-platform-10.4 --diff | less -r

• Merge the list of updated language codes across all the repositories (from the output of the commands above) and update the Release Notes in the Translations section with these language codes.
  • Only count what should be counted:
    Error

    Be careful to only count real translation changes:

    • If Weblate reorder the translations but no new translation is added, the language should not be counted.
    • If a key is renamed (i.e. deprecated and a new one introduced with the same translation content), the language should not be counted. If the translation content has changed then the user will see something different and thus it counts as a language change.
    • <add more cases here as we find them>

    At the moment the script keeps all changes of the type `<start of line>key=value`, i.e. it discard comments for ex `#Missing someKey=someValue` is not counted.

    Since it can be hard to figure out what are user changes when there are key renames, key deletions or key move, another way to view changes is to look at the Activity Stream on l10n for added or changed translations.

  • Skip duplicates and sort the final list alphabetically.

Build the release

• Restart the release
  • Skipping the npm publication
  • If the release:prepare is good and you need to restart only the release:perform
• Create the Release Branch

echo "test" | gpg -o /dev/null --local-user <KEYID> -as - && echo "Passphrase is correct"

  screen -L -Logfile /home/releaser/releases/logs/xwiki-17.9.0.log

# Perform the release from the release sources
hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ ~/maven-release.sh

Restart the release

If the build failed or if you wish to release again, perform the following steps:

• Set the version that you're building, e.g. hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ export VERSION='4.2-milestone-3'
• Navigate to the repositories that failed to build (e.g. xwiki-platform) and clean up. For example for xwiki-platform:

  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ cd xwiki-platform
  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-platform$ ~/restart-release.sh

• Fix the build if need be (you won't need to fix anything if you just want to release again for example).
• Re-launch the maven-release.sh script from /releases/xwiki-trunks to resume from where we left off, but disable the repositories which were already sucessfully released: -C (for xwiki-commons), -R (for xwiki-rendering) or -P (for xwiki-platform). For example to restart the release skipping xwiki-commons and xwiki-rendering:

  hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ ~/maven-release.sh -CR

Skipping the npm publication

In cases where xwiki-platform release needs to be restarted, but the npm publication already passed during a previous attempt, it is required to skip the npm publication. To do so, the SKIP_NPM_PUBLICATION environment variable needs to be set to true.

export SKIP_NPM_PUBLICATION=true

If the release:prepare is good and you need to restart only the release:perform

Going even further with the resuming of a failed build, in the case of release:perform, we can resume from the actual failed module. To do so, we must make some additional temporary modifications to the release script, besides the one described above which isolates the script to release only the currently failed module.

Comment out the cleanup steps done in the release_project method:

 function release_project() {
   cd $1
#  pre_cleanup
#  update_sources
#  check_branch
#  create_release_branch
#  pre_update_parent_versions
   release_maven
   post_update_parent_versions
   push_release
...

Comment out the release:prepare step in the release_maven method and add the -rf group:artefactId parameter inside the -Darguments="..." with the module you want to resume the release from. See an example below where we are resuming from org.xwiki.platform:xwiki-platform-distribution-war.

function release_maven() {
  DB_PROFILE=hsqldb
 
  echo -e "\033[0;32m* release:prepare\033[0m"
# mvn release:prepare -DpushChanges=false -DlocalCheckout=true -DreleaseVersion=${VERSION} -DdevelopmentVersion=${NEXT_SNAPSHOT_VERSION} -Dtag=${TAG_NAME} -DautoVersionSubmodules=true -Phsqldb,mysql,pgsql,derby,jetty,glassfish,legacy,integration-tests,office-tests,standalone -Darguments="-N ${TEST_SKIP}" ${TEST_SKIP} || exit -2

  echo -e "\033[0;32m* release:perform\033[0m"
  mvn release:perform -DpushChanges=false -DlocalCheckout=true -P${DB_PROFILE},jetty,legacy,integration-tests,office-tests,standalone ${TEST_SKIP} -Darguments="-P${DB_PROFILE},jetty,legacy,integration-tests,office-tests ${TEST_SKIP} -Dgpg.passphrase='${GPG_PASSPHRASE}' -Dxwiki.checkstyle.skip=true -rf org.xwiki.platform:xwiki-platform-distribution-war" -Dgpg.passphrase="${GPG_PASSPHRASE}" || exit -2

  echo -e "\033[0;32m* Creating GPG-signed tag\033[0m"
...

Manually set the git tag name that will be used for GPG signing:

## The format is MODULE_NAME-VERSION. Modify accordingly.
export TAG_NAME="xwiki-platform-8.3-milestone-2"

Run the release script to resume the release of the current project:

hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-platform$ ~/maven-release.sh

Create the Release Branch

To create the stable branches before a release, you should execute the release script but disable the actual release part:

hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ ~/maven-release.sh -r

Generate Code Contributors list

• Automatically, on the agent:

  ## list_contributors.sh <start_version> <end_version>
  releaser@releaseagent-dev:~/releases/xwiki-trunks$ ~/xwiki-dev-tools/xwiki-release-scripts/list_contributors.sh 10.4 10.5-rc-1

• Manually (on the agent or locally, if the automatic option fails):
  • Collect the list of code contributors for this release by running the following command on each branch on each repository that has been released (xwiki-commons, xwiki-rendering, xwiki-platform):

    > git fetch --tags
    > git log --pretty=format:"%an" <previousTag>..<nextTag> | sort -u
    ## Example:
    > git log --pretty=format:"%an" xwiki-commons-10.4..xwiki-commons-10.5-rc1 | sort -u
    > git log --pretty=format:"%an" xwiki-rendering-10.4..xwiki-rendering-10.5-rc1 | sort -u
    > git log --pretty=format:"%an" xwiki-platform-10.4..xwiki-platform-10.5-rc1 | sort -u
    ## For **final versions**, always compare with the previous final, not with the previous RC:
    > git log --pretty=format:"%an" xwiki-platform-10.4..xwiki-platform-10.5 | sort -u

• Try to remove duplicates and infrastructure users (like xwikirogci or XWiki) and sort alphabetically.
• Update the Release Notes in the Credits section with the contributors list.

Handle Backward Compatibility Actions

Update Backward Compatibility in the release note

The Backward Compatibility report is automatically generated in the Release Notes page by the {{backwardCompatibilityReport134 version="<version>"/}} macro which does the following:

• Gets the revapi ignores from the pom.xml of xwiki-commons, xwiki-rendering and xwiki-platform GitHub repositories and store them in an xobject in the Release Note page. If you wish to regenerate the content from GitHub just delete this xobject.
• Displays the ignores

Update the backward compatibility setup in the build

If you're releasing a final or bugfix, perform the following operations on the agent or on your local machine:

• Automatically, on the agent:

  ## backward_compatibility_cleanup.sh <new_version>
  releaser@releaseagent-dev:~/releases/xwiki-trunks$ ~/xwiki-dev-tools/xwiki-release-scripts/backward_compatibility_cleanup.sh 12.3
  ...
  ...
  ...
  Also update the [master] branch? (Only if new release version is 'bigger' than the existing one. Y for final, N for most bugfixes except bugfix of a very recent final) :
  [y/N]

  • When asked Also update the [master] branch?, only answer y (yes) in one of these 2 cases, otherwise answer N (no):
    1. (common) if you are releasing a final version (e.g. 12.3, from stable-12.3.x that was recently created by the release candidate that was released 2 weeks ago) OR
    2. (less common) if you are releasing a bugfix version that would be "bigger" than any existing version (e.g. 12.3 was just released, or even 12.3-rc-1, however, a critical bug was discovered and we quickly release the bugfix version 12.3.1. For this bugfix, you also need to update master, because it acts more like a final version than a bugfix and is 'bigger' than what was released until then.)
  • If releasing a final version and while waiting for this bug to be fixed, review the master branch for any Revapi ignore that would have been added after the RC release and removed by the script. If there's any, put them back.
• Manually (on the agent or locally, if the automatic option fails):
  • Checkout master for xwiki-commons and edit the top level pom.xml to update the xwiki.compatibility.previous.version. Set the value to be your release you've just done.

    ## Replace the previous version with the new version (e.g. 10.4 with 10.5).
    hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ git checkout master
    hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ sed -i 's/<xwiki.compatibility.previous.version>.*</<xwiki.compatibility.previous.version>10.5</' pom.xml
    ## Double check that it has been updated
    hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ git diff
    ## Commit and push
    hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ git commit -a -m "[release] Updated compatibility previous version to the one just released."
    hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks/xwiki-commons$ git push origin master

  • On master, you have to remove ignores from 3 locations and then commit & push the changes (git commit -a -m "[Misc] Removed revapi ignores from the previous version"):
    • xwiki-commons/xwiki-commons-core/pom.xml
    • xwiki-rendering/pom.xml
    • xwiki-platform/xwiki-platform-core/pom.xml
    • If you are doing this on the agent, you can use nano to open the files and use CTRL+W to search for revapi. Once you have found the JSON formatted ignores, select all the lines you want to delete by using CTRL+SHIFT+6 and press CTRL+K to delete the selected lines. Exit the exitor with CTRL+X, y, ENTER (when asked if the changes should be saved) and commit the changes for each repository.
  • Make sure the xwiki.compatibility.previous.version value is changed also on the branch from where you've released, and that the ignores are cleaned too from the branch, since future releases (ex. 10.5.1) are final releases too.

Clean up identity

# Git identity
hudsonagent@vagent-1-1-dev:~/releases/xwiki-trunks$ cd
hudsonagent@vagent-1-1-dev:~$ cp .gitconfig.default .gitconfig

# GPG key
hudsonagent@vagent-1-1-dev:~$ gpg --delete-secret-and-public-keys $(gpg --list-secret-keys | grep ^sec -A 1 | tail -n 1 | awk '{ print $1 }')

# npm token
unset NPM_TOKEN

# Local changes to the release-scripts (maven-release.sh, user/password in release-translations.sh, etc.)
# Double check that you are not removing any improvement you have made to the release scripts that should be committed instead ;)
hudsonagent@vagent-1-1-dev:~$ cd xwiki-dev-tools; git status; git diff; git checkout .

 Then don't forget to remove the Agent's SSH Key from your Github Account and to remove the access token from https://www.npmjs.com/.

Blog post on xwiki.org

Create a new blog post on xwiki.org. Example content:

• Page name: xwiki-<version>-released where <version> is using the short version format, such as 17.10.0RC1 (e.g., for 16.10.16, the page name to input in the blog creation form is xwiki-16.10.16-released, the dots are replaced with dashes by our naming strategy, creating the Blog.xwiki-16-10-16-released page)
• Blog title: XWiki 15.3 Released
• Blog full content:

  The XWiki development team is proud to announce the availability of [[XWiki 17.6.0RC1>>doc:xwiki:ReleaseNotes.Data.XWiki.17\.6\.0RC1.WebHome]].
  
  This release brings performance improvements for icons, more control over the sorting in document trees. You will also be able to install and test a new (still very experimental) BlockNote-based WYSIWYG editor, and developers will benefit from a new, also still experimental, endpoint to help implementing Yjs-based real-time collaboration. This release contains security fixes, with the highest severity being 8.7/10.
  
  See the [[release notes>>doc:xwiki:ReleaseNotes.Data.XWiki.17\.6\.0RC1.WebHome]] for more information.

• Blog extract content:

  The XWiki development team is proud to announce the availability of [[XWiki 17.6.0RC1>>doc:xwiki:ReleaseNotes.Data.XWiki.17\.6\.0RC1.WebHome]]. This release brings performance improvements for icons, more control over the sorting in document trees. You will also be able to install and test a new (still very experimental) BlockNote-based WYSIWYG editor, and developers will benefit from a new, also still experimental, endpoint to help implementing Yjs-based real-time collaboration. This release contains security fixes, with the highest severity being 8.7/10. See the [[release notes>>doc:xwiki:ReleaseNotes.Data.XWiki.17\.6\.0RC1.WebHome]] for more information.

• Blog Categories: Releases. If releasing a bugfix version or a final version, also add What's New for XWiki and What's New for XWiki: Admin User.

Update fr.wikipedia.org

fr.wikipedia.org is different from en.wikipedia.org. You can not simply edit the XWiki page and update the version value (or a special template page like it is done for en). Instead, you need to press the "pencil" icon next to the version value and be redirected to https://www.wikidata.org/wiki/Q526699?uselang=fr#P348, the site that manages the data displayed by the infobox. There, you need to:

• Add a new version entry to the existing list ("+ ajouter une valeur" button at the end of the list)
• Enter the version number
• Press "+ ajouter un qualificatif"
• Type "date de publication" in the suggest box and select it.
• Press "+ ajouter un qualificatif" again and add "type de version" with "version stable" or "version avec support à long terme" as value, depending on the released version
• Click on "ajouter une référence" and add "URL de la référence", "date de consultation", "titre" and "date de publication". Check the previous XWiki versions to see what values to use.
• On the right, type the release date in the format "26 janvier 2021"
• Click on the control left to the version you have entered (the one with a small arrow pointing up) and select "Rang prefere". This will make it selected and displayed on the XWiki page.
• Press "publier" to publish you new version
• Click "modifier" for a version just before the one you have added that has the small arrow control pointing up.
• Click on the arrow control and select "Rang normal". This will make it deselected so that it is not displayed on the XWiki page.
• Check the XWiki page if the new version and date are properly displayed

Update Wikimatrix

This step must be performed only for the latest final releases (not bugfixes or RCs).

If it's the first time please register on https://www.wikimatrix.org and ask someone (Thomas for example) to get admin access to XWiki project for you.

Note: The only exception when a bugfix would be added here is when it would be done for the latest released final version (e.g. latest final is 10.2 and the bugfix is 10.2.1).

Forum Announcement

• Add a new post to the users forum on https://forum.xwiki.org/c/News
• Example post:
  • Subject: XWiki <version> released
  • Content:

    The XWiki development team is proud to announce the availability of XWiki <version>.
    <short summary>
    
    You can download it here: https://www.xwiki.org/xwiki/bin/view/Main/Download
    
    Make sure to review the release notes:
     https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/<short version>
    
    Thanks for your support
    -The XWiki dev team

  • Category: News & Events
  • Tags: release

Announce on Mastodon

Announce the new release on Mastodon, by logging in with the XWiki.org user account, following the template below

#XWiki $VERSION has been #released! Check it out: https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/$VERSION

$SUMMARY

Where:

• $VERSION is the newly released version
• $SUMMARY is the same short summary use for the blog post but with internal URLs removed (readers will click the link to the RN for details)

Mastodon messages can be sent from the web from https://fosstodon.org/@xwikiorg/ but CLI tools such as toot can also be used.

Rebuild Debian Distribution

The XWiki Debian distribution is automatically rebuilt every day using a crontab on maven.xwiki.org.

However, in order for the Debian distribution to be ready when we announce a new version, it's a good thing to force rebuild it.

This is achieved by logging on maven.xwiki.org with the maven user and trigger a rebuild of the Debian index.

Run the script.

nohup /home/maven/xwiki_scanpackages.sh &

This start the index update in the background, you can leave.

Force Extensions Update

In order to have up to date versions on https://extensions.xwiki.org you should trigger the Batch importer scheduler (from the first node of the cluster).

Update Docker Images

Updating the images and submitting the DockerHub official images Pull Request are automated as Gradle tasks in the XWiki Docker repository. You only review, commit and push the change in between. No JIRA issue is needed for this task.

Prerequisites: a local clone of the XWiki Docker repository with a clean working tree, Docker installed and running, and an authenticated GitHub CLI (check with gh auth status). The tasks drive docker, git and gh, so they run on Linux and macOS.

1. Update everything and verify it boots.
   • Run: ./gradlew release

   This does the whole pre-push work, for every supported XWiki cycle:

   • resolves the latest final XWiki version released on that cycle's line, and downloads the WAR to compute its SHA-256;
   • reads the three JDBC driver versions (MySQL, MariaDB, PostgreSQL) from that cycle's own xwiki-platform POM, and downloads from Maven Central the ones that moved forward, to compute their SHA-256;
   • updates the LibreOffice version XWiki supports (the LTS one) and its per-architecture SHA-256;
   • regenerates the Dockerfiles and resources of every image tag, plus the Docker Build GitHub Actions workflow;
   • smoke-tests the cycles whose versions moved: for each, it builds the postgres-tomcat image (plus the image of any database whose JDBC driver moved) with the classic Docker builder, the one the Docker Official Images infrastructure uses, boots it with docker compose on port 18080, waits until its REST API reports the expected XWiki version, then tears it down and removes its volumes.

   Nothing is downgraded: a version pinned ahead of what is published is left alone rather than reverted.

2. Review, commit and push.
   • Review the diff: versions.json plus the regenerated version directories.
   • Commit both versions.json and the regenerated directories together and push to master, otherwise CI rejects the push.
3. Submit the DockerHub official images Pull Request.
   • Run: ./gradlew submitOfficialImage

   This regenerates the images, generates the official library file from versions.json, and opens the Pull Request against docker-library/official-images from your GitHub fork (no local clone needed, and no SHA-1 to copy by hand).

   It refuses to submit what docker-library could not fetch: a dirty working tree (including images that were not regenerated before being pushed), a HEAD that is not on master, or a Pull Request still open from a previous run.

   • Add -PdryRun to only generate the file and show the diff against the published one, without opening a Pull Request: ./gradlew submitOfficialImage -PdryRun
4. Check whether the documentation requires updates due to the new XWiki version.
   • If documentation changes are needed, update the relevant files before merging the Pull Request, or inform Eleni to update the documentation accordingly.

Test Docker Image

This section describes how to try an XWiki Docker image out by hand, for a deeper look than the automated smokeTest gives: to browse the wiki, to check a change to the template/ directory, or to investigate a failing smoke test. Each version/variant directory holds a docker-compose.yml that already wires XWiki to its database, so there is no network and no volume to create by hand.

1. Make sure Docker is installed and running.
   • Linux (except Ubuntu): start the Docker service: sudo systemctl start docker.
   • MacOS and Windows: install Docker Desktop if needed, then start it.
2. Navigate to the directory of the image to test, i.e. <cycle>/<database>-tomcat. Example: cd 18/postgres-tomcat.
3. Optionally, refresh the Tomcat base image, so that the build starts from its latest patch: docker pull $(grep '^FROM' Dockerfile | head -1 | awk '{print $2}').
4. Build the image under the tag the Compose file expects.

   The generated docker-compose.yml has no build section, only image: xwiki:${XWIKI_VERSION}-<database>-tomcat, so a plain docker compose up would run the image published on DockerHub, not the one in your working copy. Build that exact tag first, so that your local image shadows the remote one:

   DOCKER_BUILDKIT=0 docker build -t "xwiki:$(grep XWIKI_VERSION .env | cut -d= -f2)-$(basename $PWD)" .

   • DOCKER_BUILDKIT=0 selects the classic builder, which is the one the Docker Official Images infrastructure and the repository's CI use. The two builders do not accept the same Dockerfiles, so a BuildKit build can pass on something that will fail upstream.
   • At release time this build is the only way to test the image at all: the official image for a version is only built once the docker-library Pull Request has been merged, so the tag does not exist on DockerHub yet.

   Warning

   This overwrites whatever your Docker holds under that tag, including the published official image of that version if you had pulled it. docker pull xwiki:<version>-<database>-tomcat brings it back.

5. Start XWiki and its database: docker compose up (add -d to get your terminal back, and follow the logs with docker compose logs -f web).

   Only one variant can run at a time: the Compose file hardcodes the host port 8080 and container names that depend on the database rather than on the cycle. Stop the running one (see Clean Up below) before starting another.

   The versions used come from the generated .env file (XWIKI_VERSION, DB_USER, DB_PASSWORD, DB_DATABASE). XWIKI_VERSION is what the image tag above is built from, so override it by editing .env or by exporting it in the shell before docker compose up.

6. Verify the instance.
   • Open http://localhost:8080 in a browser and complete the XWiki setup process.
   • The running version can also be checked without a browser: the root REST resource reports it in its <xwiki version="..."/> element (this is what the automated smoke test polls): curl -s http://localhost:8080/rest.

Clean Up

From the same version/variant directory, stop the instance and remove its containers, its network and its volumes:

docker compose down -v

To also remove the image that was built above: docker rmi "xwiki:$(grep XWIKI_VERSION .env | cut -d= -f2)-$(basename $PWD)".

Indicate Security issues

Indicate if there are security issues in the release notes summary with This release contains security fixes, with the [[highest severity being XXX/10>>doc:dev:Community.SecurityPolicy.WebHome||anchor="HSeverity"]].