Skip to content

Release Workflow#

We have regular releases and bugfix releases. We use 20.06 as an example for a regular release and 22.06.1 as an example for a bugfix release.

Release steps:

  1. Set the variables used in the following steps as in this example for a regular release: 
    RELEASE=20.06
BRANCH=20.06
TAG=20.06.0
    Set them as in this example for a bugfix release: 
    RELEASE=22.06.1
BRANCH=22.06
TAG=22.06.1
  2. Regular releases only: make sure that you are on the commit on which you want to base the release.
  3. Bugfix releases only: check out the release branch and cherry-pick each commit with hash HASH that you want to include: 
    git checkout release-$BRANCH
git cherry-pick HASH
  4. Make sure that the list of contributors and copyright years in the README.md file are up to date.
  5. Make sure the changelog (see ChangelogFormat) is up to date and committed. In particular:
    1. Make sure the changelog includes the line giving the date of the release.
    2. Add a new section like ## Fast Downward 20.06 or ## Fast Downward 22.06.1 and gather all changes since the last release from the commit messages. Use an existing regular/bugfix release as an example.
  6. Make sure that the working directory is clean and that any last-minute changes from the above steps are committed.
  7. Update version number and create branches, tags and recipe files by running the prepare-release.sh script: 
    ./misc/releases/prepare-release.sh $TAG
  8. Verify the following manually:
    1. The fast-downward-$RELEASE.tar.gz tarball created in the previous step contains the appropriate files.
    2. Branches and tags were created as expected. In a bugfix release, a tag like 22.06.1 should have been created on the existing release branch 22.06.
    3. A new commit was created with the right recipe files and version changes.
  9. Push all changes. 
    git push --all
git push --tags
  10. Make sure that all Github actions are green on the release branch.
  11. Build the Docker image and push it to the Docker Hub. Note that we build the 20.06/22.06 Docker image, not 20.06.0/22.06.1. Under normal conditions, Docker needs root rights. The actual push to Docker hub needs appropriate credentials. Malte has them; not sure anyone else does. (Please edit if you do.) 
    sudo ./misc/releases/push-docker.sh $BRANCH
  12. Build the Apptainer image: 
    apptainer pull fast-downward.sif docker://aibasel/downward:$BRANCH
    Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.3.6.
  13. Test:
    • that we can build and successfully run the planner from the produced tarball
    • that we can successfully run the planner from the produced Apptainer image, including a configuration using SoPlex
    • that we can successfully run the planner from the produced Vagrantfile (automatically includes SoPlex; to also build the VM with CPLEX, you need an environment variable DOWNWARD_LP_INSTALLERS that points to a directory containing the CPLEX installer in the correct version)
  14. Regular releases only: create a documentation page for the release in the downward-markdown repository. We suggest starting from a copy of the page for the latest release in docs/releases.
    1. Update the date and release version name.
    2. Update the links and references in section "Downloads".
    3. Update the changelog.
    4. Add the tarball to a new folder for the release in docs/files.
    5. Add the Vagrant file created by the prepare-release.sh script to the same folder.
    6. Create a link in docs/releases/index.md to the page of the new release.
  15. Bugfix releases only: update the documentation page of the release (for bugfix release 22.06.1, reuse the release page 22.06). See the page for release 22.06 for an example. The Vagrantfile does not need to be updated for a bugfix release.
    1. Adjust the date and mention the bugfix release version name.
    2. Update the changelog.
    3. Update the name of the tarball (it should include the bugfix number) and add the tarball to the respective folder in docs/files.
    4. Update the bash instructions.
  16. Regular releases only: create a documentation version for the release in the downward-markdown repository.
    1. Branch from the head-docs branch to a new branch release-$TAG and update README.md file to state that this is the branch for that release (instead of being auto-generated like the head-docs branch). This assumes that you make a release from the current HEAD of main in the Fast Downward code repository. If not, you can modify the branch as described for a bugfix release (next step).
    2. Add an entry for the release in releases.json of the main branch. Move the latest alias to the new release.
  17. Bugfix releases only: create a documentation version for the release in the downward-markdown repository.
    1. Branch from the earlier release-{$TAG-1} branch to a new branch release-$TAG and update README.md file to state that this is the branch for that bugfix release.
    2. Make necessary changes in the documentation in this branch. If the generated documentation for the search plugins has changed, generate it with the misc/autodocs/generate-docs.py script in the code repository. It writes the documentation to docs/search there. You just have to copy the content into docs/search of the new branch.
    3. Update entry for the release in releases.json of the main branch, e.g. from "24.06.0" to "24.06.1".
  18. Create a new release on github:
    1. On https://github.com/aibasel/downward/releases click on Draft a new release.
    2. Set Tag to release-$TAG, Release Title to $RELEASE, and Description to For information about this release, please visit the [Fast Downward website](https://www.fast-downward.org/$BRANCH/releases/$BRANCH/)..
    3. Click on Publish Release.
  19. Send an announcement e-mail to the Fast Downward list including changelog information.
  20. Send the same announcement as a message in the Fast Downward Discord server.