Skip to content

Release Workflow#

We have regular releases and bugfix releases. We use 26.6 as an example for a regular release and 26.6.1 as an example for a bugfix release.

Note: We moved away from Ubuntu's naming convention of two-digit months (26.06 instead of 26.6) because we now use Fast Downward version numbers on PyPI, which removes such leading zeros.

Release steps:

  1. Check that our information on required Python versions is consistent. Our current policy is to require the oldest Python version tested by one of the Github actions. The tested versions are shown in README.md; the source of truth for these are the yml files defining the github actions (grep -R 'python:' .github/workflows from the repository root). The lowest version number should be the same as the minimum required one in src/translate/pyproject.toml.

  2. Set the variables used in the following steps as in this example for a regular release: 

    RELEASE=26.6
BRANCH=26.6
TAG=26.6.0
    Set them as in this example for a bugfix release: 
    RELEASE=26.6.1
BRANCH=26.6
TAG=26.6.1

  3. Regular releases only: make sure that you are on the commit on which you want to base the release.
  4. 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
  5. Make sure that the list of contributors and copyright years in the README.md file are up to date.
  6. 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 26.6 or ## Fast Downward 26.6.1 and gather all changes since the last release from the commit messages. Use an existing regular/bugfix release as an example.
  7. Make sure that the working directory is clean and that any last-minute changes from the above steps are committed.
  8. Update version number and create branches, tags and recipe files by running the prepare-release.sh script: 
    ./misc/releases/prepare-release.sh $TAG
  9. 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 26.6.1 should have been created on the existing release branch 26.6.
    3. A new commit was created with the right recipe files and version changes.
  10. Push all changes. 
    git push --all
git push --tags
  11. Make sure that all Github actions are green on the release branch.
  12. Build the Docker image and push it to the Docker Hub. Note that we build the 26.6 Docker image in both cases, not 26.6.0/26.6.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
  13. 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.
  14. 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)
  15. Build and upload the Python package to PyPI (requires credentials, Gabi has them.)
    1. Prepare the Python package. 
      ./misc/releases/prepare-translator-package.sh $TAG
    2. Follow the instructions printed by the script to test and upload the package to PyPI.
  16. 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 and docs/releases/SUMMARY.md to the page of the new release.
  17. Bugfix releases only: update the documentation page of the release (for bugfix release 26.6.1, reuse the release page 26.6). 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.
  18. 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.
  19. 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 "26.6.0" to "26.6.1".
  20. 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.
  21. Send an announcement e-mail to the Fast Downward list including changelog information.
  22. Send the same announcement as a message in the Fast Downward Discord server.