GitLab personal access token

The release process shell script described below triggers merge requests and monitors the continuous integration run that creates and signs the binary artifacts. In order to do this, it needs a personal access token with api and write_repository scopes. This access token can be created by users directly from their GitLab account (User Settings → Access Tokens) or by following the link below: https://gitlab.orekit.org/-/user_settings/personal_access_tokens?scopes=api,write_repository

Note that the access token is only visible once from this page, so it must be saved before leaving the page. The GitLab personal access token lifetime is limited to 11 months, this step must therefore be renewed from time to time.

Forum API Key

The release process shell script described below creates the vote topic automatically on the Orekit forum https://forum.orekit.org. In order to do this, it needs an API key to post on behalf of the release manager. There are no automatic processes for setting up such a key, candidate release managers should just send direct messages to the forum administrators, and they will proceed with generating the API key and sending it, using any means they see fit.

Sonatype central portal

Binary artifacts are published in the maven central repository, which is managed by Sonatype. The org.orekit namespace is used for these artifacts, and only people that have been identified as allowed to publish releases can push binary artifacts for publication.

In order to publish, candidate release managers should therefore create an account on Sonatype central repository using the central portal login page. Once the account has been created they should ask existing release managers to add them to the allowed list for the org.orekit namespace.

Note that the central portal account and the associated credentials are different from the legacy OSSRH system that was used before Orekit 13.1. This implies that people that were able to publish Orekit releases prior to Orekit 13.1 must create a new account on the new central portal system, their older account on legacy OSSRH is obsolete.

After creating the account on Sonatype central portal, release managers should create a User Token. This is done by login to central portal login page, selecting the View Account item from the menu drop list at the upper right of the page (small button that displays the start of the username) and selecting the Generate User Token button in the Setup Token-Based Authentication page. This will generate a token with a small random Id and a long random password.

Note that Orekit does not use the central-publishing-maven-plugin. The reason is that we need to provide public access to the binary artifacts for the voting process. As of summer 2025, the central portal does not allow that, it restricts the visibility of staged artifacts before they are officially published. So the Orekit process is to use the Orekit Nexus repository at https://packages.orekit.org/ during the voting period, and to transfer the artifacts to central portal only after the vote has been tallied and publication has been allowed.

As we don't use the central-publishing-maven-plugin, there is no need to copy the xml snippet that is generated by central portal into the $HOME/.m2/settings.xml file. Users could just store these credentials in any password manager they prefer, the script will ask for them when needed.

The Sonatype publish portal guide explains everything in detail, but this release guide is enough to perform a release.

Note on maven plugins versions

Maven plugins should be updated from time to time, but it is probably unwise to do it at release time, it is too late, so these updates should happen well before the release. All maven plugin versions are gathered at one place, in a set of properties in pom.xml:

<!-- Project specific plugin versions -->
<orekit.spotbugs-maven-plugin.version>3.1.11</orekit.spotbugs-maven-plugin.version>
<orekit.jacoco-maven-plugin.version>0.8.3</orekit.jacoco-maven-plugin.version>
<orekit.maven-assembly-plugin.version>3.1.1</orekit.maven-assembly-plugin.version>
...

You can find the latest version of the plugins using the search feature at https://central.sonatype.com/. The properties name all follow the pattern orekit.some-plugin-name.version, the plugin name should be used in the web form to check for available versions.

Beware that in some cases, the latest version cannot be used due to incompatibilities. For example, when a plugin was not recently updated and conflicts appear with newer versions of its dependencies.

Beware also that some plugins use configuration files that may need update too. This is typically the case with maven-checkstyle-plugin and spotbugs-maven-plugin. The /checkstyle.xml and /spotbugs-exclude-filter.xml files may need to be checked.

Before committing these changes, you have to check that everything works. So run the following command, taking care to use the Java version that matches the compatibility requirements (Java 8 at time of writing):

mvn clean
LANG=C JAVA_HOME=/path/to/correct/java/version PATH=${JAVA_HOME}/bin:$PATH mvn -Prelease site

If something goes wrong, either fix it by changing the plugin configuration or roll back to an earlier version of the plugin.

Browse the generated site starting at page target/site/index.html and check that everything is rendered properly.

When everything runs fine and the generated site is OK, then you can commit the changes:

git add orekit/pom.xml orekit/checkstyle.xml orekit/spotbugs-exclude-filter.xml
git commit -m "Updated maven plugins versions."

2. Run the prepare-release.sh script

There is a prepare-release.sh shell script in the scripts directory that automatically performs all the release steps by itself. It asks questions and waits for confirmation at various stages. It creates branches, checks them out, performs some automated edition on several files, commits the changes, sets up tags that will be recognized by Orekit Continuous Integration setup, and pushes everything to Orekit GitLab forge.

When releasing a major or minor version, the script automatically posts a vote topic on the Orekit forum so that community and PMC members can vote on the release. When releasing a patch version, the script skips the vote topic creation and continues up to promoting the release from staging to published.

The shell script performs the release on a temporary branch that is merged to the release branch after the last automatic file edition.

When the temporary branch is remotely merged to the release branch on the Orekit GitLab forge, the Continuous Integration is automatically triggered. It performs a full build, signs the artifacts using the release key and puts them in a staging repository, where users will later be able to review them during the voting period.

Several steps (creating the release branch, merging the temporary branch into the release branch…) are performed remotely, from the release manager computer to the Orekit GitLab forge (this is the reason why release managers need a GitLab personal access token). Several of these steps take some time, for example when the merge request is created, it is not executed immediately. There are several waiting loops that monitor the progress of these steps, polling the forge regularly. These loops display a timestamped waiting message evey 5 seconds (every 30 seconds for the long pipeline run loop) until the operation is performed, and stop the release process if the operation exceeds a timeout. Branch creation, merge request creation, and merge request completion have a 10 minutes timeout but should typically be completed in one or two minutes. Continuous Integration pipeline start has a 30 minutes timeout as runners may be busy with already running compilations. Once started, Continuous Integration pipeline run time has a 60 minutes timeout. The final step (creating the vote thread) is triggered only if the Continuous Integration pipeline succeeds.

If something goes wrong or if the release manager answers “no” to one of the confirmation questions triggered by the script or interrupts the script by a signal like hitting ctrl-C, the script removes all the branches and tags it created (both locally and on the Orekit GitLab server) and stops. This ensures everything remains clean. The last chance to stop the release process corresponds to the question about posting the vote thread to the forum.

This script must be run from the command line on a computer with several Linux utilities (git, sed, xsltproc, curl…), with the git worktree already set to the start branch (i.e., develop or a patch branch):

sh scripts/prepare-release.sh

Here are the steps the script performs on its own, asking for user confirmation before any commit:

- perform safety checks (files and directories present, utilities available, java version)
- ask for GitLab personal access token
- check if the release is a major, minor or patch release
  using the -SNAPSHOT version number from the current branch `pom.xml`
- set up a release candidate number, starting from 1 or incrementing existing RC tags
- for first release candidate of major or minor release, create a release-X.Y branch from develop
  (reuse existing branch otherwise)
- checkout the release-X.Y branch
- create a RCn-X.Y branch
- checkout the RCn-X.Y branch
- merge the start branch into the RCn-X.Y branch
- drop -SNAPSHOT version number from `pom.xml` and commit the change
- compute candidate release date, allocating 5 days for the vote
- update `changes.xml` with release date and release type and commit the change
- update downloads and faq pages and commit the changes
- push the RCn-X.Y branch to origin
- if the release-X.Y branch does not exist on the Orekit GitLab forge, create it remotely
- trigger a merge request from RCn-X.Y branch to release-X.Y branch
  (this will trigger full build, signing and deployment to Orekit Nexus instance)
- switch to release-X.Y branch
- pull merged branch from origin
- tag the RCn-X.Y branch with tag X.Y-RCn and push the tag to origin
- monitor continuous integration run
- if the release is a patch release, call immediately the `successful-vote.sh` script
- if the release is a major or minor release, create the vote topic automatically on the forum
  (the API key for posting to the forum will be asked for at this point)

3. Voting period

For major and minor releases, the script generates the vote topic on the forum by itself. The voting period is 5 days, so release managers should wait until this time has elapsed before concluding. Of course, if one of the voters raises concerns that should be addressed, the vote can be canceled before the 5-day duration.

sh scripts/successful-vote.sh

- perform safety checks (files and directories present, utilities available)
- check the branch to see it is really a release branch
- check the tag for the successful release candidate
- retrieve maven artifacts from the Orekit Nexus repository
- publish maven artifacts to the central portal
- tag the repository
- push the tagged repository to origin
- merge release branch to main branch
- push main branch to origin
- merge main branch to develop branch
- update version number in `pom.xml` for next development cycle
- update version number in `changes.xml` for next development cycle
- push develop branch to origin

4. Synchronize the GitHub mirror

To enhance the visibility of the project, a mirror is maintained on GitHub. The releases created on GitLab are not automatically pushed on this mirror. They have to be declared manually to make visible the vitality of Orekit.

1. Login to GitHub
2. Go to the Orekit releases page
3. Click on the Draft a new release button
4. In the “Tag version” field of the form and in the “Release title” field, enter the tag of the release to be declared
5. Describe the release as it has been done on GitLab
6. Click on “Publish release”

Github automically adds two assets (zip and tarball archives of the tagged source code)

5. Update Orekit site

Several edits need to be done to the Orekit website after the vote.

First, clone the current code:

git clone https://gitlab.orekit.org/orekit/website-2015

Switch to develop branch. Edit overview.html:

• (If needed) Update the new Hipparchus version.
• Update the overview.png image with the new version numbers.
• (If needed) Update the Features section with the new features added by the new version of Orekit.

Create a new post for the release in _post/, it will be visible in the News page (see section Announce Release for the content of the post).

Push the modifications on develop branch, wait until the pipeline on GitLab is finished, then the test website will be updated.

Check that everything looks nice and then merge develop on main branch and push the modifications. When the GitLab pipeline is finished, the official website should be updated according to your changes.

6. Close X.Y milestone

In GitLab, navigate to Projects > Orekit > Issues > Milestones. Click “Close Milestone” for the line corresponding to the release X.Y.

7. Announce release

The last step is to announce the release by creating a post in the Orekit announcements category of the forum with a subject line of the form:

Orekit X.Y released

and content of the form:

The Orekit team is pleased to announce the release of Orekit version X.Y.
This is a major/minor/patch version.
The main changes are:

  - feature 1 description
  ...
  - feature n description

This version depends on Hipparchus X'.Y'

For complete release notes please see:
https://www.orekit.org/site-orekit-X.Y/changes-report.html

The maven artifacts are available in maven central. 
The source and binaries can be retrieved from the forge releases page:
https://gitlab.orekit.org/orekit/orekit/-/releases