Orekit Release Guide

This release guide is largely inspired from Orekit Release Guide.
Note that:


  • Obtain private key of the Orekit Signing Key, key id: 0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B

If you need help with either ask on the development section of the Orekit forum.

Use mvn -ep to generate an encrypted password for the Orekit Signing Key.

Verify the status of develop branch

Before anything, check on your local repository that everything is fine on develop branch.
There should be no Maven, Java, Javadoc, Checkstyle and SpotBugs error or warning. If not, fix the warnings and errors first!

To check on this inspect your local IDE for Checkstyle and Java errors.
Then for SpotBugs, Java, Javadoc and Checkstyle inspection run

mvn clean javadoc:javadoc verify site

Prepare Git branch for release

Release will be performed on a dedicated branch, not directly on master or develop branch. So a new branch must be created as follows and used for everything else:

git branch release-X.Y
git checkout release-X.Y

Update maven plugins versions

Release is a good opportunity to update the maven plugin versions. They are all gathered at one place, in a set of properties in orekit-tutorials/pom.xml:

<!-- Project specific plugin versions -->

You can find the latest version of the plugins using the search feature at http://search.maven.org/#search. The properties name all follow the pattern orekit-tutorials.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:

mvn clean
LANG=C mvn clean javadoc:javadoc 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."

Updating changes.xml

Finalize the file /src/changes/changes.xml file.

The release date and description, which are often only set to TBD during development, must be set to appropriate values.

Replace the TBD description with a text describing the version released: state if it is a minor or major version, list the major features introduced by the version etc. (see examples in descriptions of former versions).

Commit the changes.xml file.

git add src/changes/changes.xml
git commit -m "Updated changes.xml for official release."                                                        

Change library version number

The pom.xml file contains the version number of the library. During development, this version number has the form X.Y-SNAPSHOT. For release, the -SNAPSHOT part must be removed.

Commit the change:

git add pom.xml
git commit -m "Dropped -SNAPSHOT in version number for official release."

Tag and sign the git repository

When all previous steps have been performed, the local git repository holds the final state of the sources and build files for the release.
It must be tagged and the tag must be signed.
Tagging and signing is done using the following command:

git tag X.Y -s -u 0802AB8C87B0B1AEC1C1C5871550FDBD6375C33B -m "Version X.Y."

The tag should be verified using command:

git tag -v X.Y

Pushing the branch and the tag

When the tag is ready, the branch and the tag must be pushed to Gitlab so everyone can review it:

git push --tags origin release-X.Y

Wait for the continuous integration job to run and check that everything works fine.

Generating signed artifacts locally

Contrary to Orekit library, the Orekit Tutorials artifacts are not pushed on Sonatype OSS site.
The artifacts only need to be generated locally and updated on the Gitlab forge afterwards. To generate the signed artifacts (and the site again) locally run:

mvn clean verify site install -Prelease

During the generation, maven will trigger gpg which will ask the user for the pass phrase to access the signing key.
Maven didn’t prompt for me, so I had to add -Dgpg.passphrase=[passphrase]

Once the commands ends, check that your ./target directory contains the expected artifacts with associated signatures and checksums:

  • orekit-tutorials-X.Y.pom
  • orekit-tutorials-X.Y.jar
  • orekit-tutorials-X.Y-sources.jar
  • orekit-tutorials-X.Y-javadoc.jar

The signature and checksum files have similar names with added extensions .asc.

Merge release branch into master branch

Merge the release-X.Y branch into the master branch to include any changes made. The master branch always contains the latest release of the library.

git checkout master
git merge --no-ff release-X.Y

Merge master branch into develop branch

Merge the updated master branch into the develop branch to include any changes made. Then updated the version numbers to prepare for the next development cycle.

git checkout develop
git merge --no-ff master

Edit pom.xml version to SNAPSHOT and make space in the changelog for new changes. Then commit and push.

Upload to gitlab

Navigate to Self > Settings > Access Tokens. Enter a name, date, and check the “api” box, then click “Create personal access token”. Copy the token into the following command:

for f in $( ls target/orekit-tutorials-X.Y*.jar{,.asc} ) ; do
    curl --request POST --header "PRIVATE-TOKEN: <token>" --form "file=@$f" \

Copy the URLs that are printed.

Next, navigate to Projects > Orekit > Repository > Tags. Find the X.Y tag and click the edit button to enter release notes. Paste the URLs copied from the step above.

Navigate to Projects > Orekit > Releases and make sure it looks nice.

Update Orekit site

Several edits need to be made to the Orekit website. Fetch the current code:

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

Edit download/.htaccess and replace the URLs of of the 3 Orekit artifacts with the ones created by gitlab in the previous step.

Edit download.html and update the URLs to point to the new Orekit artifacts.

Edit _layouts/home.html and edit the text of the bug button to use the new version.

Edit _config.yml and add the new version to the list of versions.


jekyll serve

and make sure the website looks nice. View it on http://localhost:4000/

If everything looks good publish the changes by running:


Mark resolved issues as closed

In gitlab, if it hasn’t been done already, select all the issues included in the release and close them. Navigate to Projects > Orekit > Orekit Tutorials Issues. Search for label:Resolved. Make sure they were all fixed in this release. Click “Edit Issues”, check all the boxes, set milestone to X.Y and status to closed.

Announce release

The last step is to announce the release by posting: * A news on the Orekit website; * A post on the Orekit forum list.