Differences between revisions 1 and 39 (spanning 38 versions)

Release Workflow

Assuming we want to create the 20.06 release, these are the steps we would follow:

Make sure that all Github actions are green.
Make sure that you are on the revision you want to release.
Make sure that the list of contributors and copyright years in the README.md file are up to date.
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. Replace the section title ## Changes since the last release with something like ## Fast Downward 20.06.
Make sure that the working directory is clean and that any last-minute changes done following the above steps are commited.
Update version number and create branches, tags and recipe files by running the prepare-release.sh script.
- ```
./misc/releases/prepare-release.sh 20.06.0
```
Verify the following manually:
1. The fast-downward-20.06.0.tar.gz tarball created in the previous step contains the appropriate files.
2. Branches and tags were created as expected.
3. A new commit was created with the right recipe files and version changes.
Push all changes.
- ```
git push --all
git push --tags
```
Build the Docker image and push it to the Docker Hub. Note that we build the 20.06 Docker image, not 20.06.0. Under normal conditions, Docker needs root rights, and the script needs an environment variable that points to a directory containing the SoPlex archive in the correct version. The actual push to Docker hub needs appropriate credentials. Malte has them; not sure anyone else does. (Please edit if you do.)
- ```
sudo DOWNWARD_LP_INSTALLERS=/path/to/dir/with/installer/ ./misc/releases/push-docker.sh 20.06
```
Build the Apptainer (successor to Singularity) image:
- ```
sudo apptainer build fast-downward.sif misc/releases/20.06/Singularity.20.06
```
Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.0.2.
Note: From what I understand, Apptainer doesn't actually need the recipe files that we build any more, and one could just build directly from the docker image. If someone is interested in getting rid of the recipes and modernizing the process, please speak to Malte and Florian (unless you're Malte or Florian ;-)). For now, I've left things as they are because it worked.
Test, at minimum:
- 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
Add a new empty section ## Changes since the last release to the changelog to prepare the changelog section for the next release. Commit and push.
Create a Wiki page for the release. We suggest starting from a copy of the page for the last release.
1. Update the date and release version name.
2. Update the changelog.
3. Upload the tarball as an attachment to the page.
4. Upload the Vagrant filecreated by the prepare-release.sh script as an attachment to the page.
5. Upload the fast-downward.sif Apptainer image as an attachment to the page.
6. Create a link in Releases to the page of the new release.
7. Make sure the necessary acknowledgements and links are included for SoPlex.
Create a new release on github:
1. On https://github.com/aibasel/downward/releases click on "Draft new release"
2. Set Tag to release-20.06.0, Release Title to 20.06, and Description to For information about this release, please visit the [Fast Downward wiki](https://www.fast-downward.org/Releases/20.06).
3. Click on Publish Release
Send an announcement e-mail to the Fast Downward list including changelog information.

Bugfix Releases

For a bugfix release, the prepare-release.sh script must be run while you are at the tip of the existing release branch. Otherwise, the script transparently handles the differences in the workflow for bugfix releases, so you should be able to apply the above steps with no change, except for the Wiki update. For a bugfix release such as 20.06.1, we do not create a new wiki page, but reuse the major release page (20.06). So we do not change Releases at all, but update Releases/20.06 as follows:

Change the title from Fast Downward 20.06 to Fast Downward 20.06.1.
Add a line like "Fast Downward 20.06.1 was released on July 33, 2020" below the existing line, leaving the old release date information in place.
Update the source tarball link and upload the new tarball. Don't delete the old tarball, just don't link it from anywhere in the page.
No need to update the Docker / Singularity / Vagrantfile links: we will at all times keep one single version of these releases, the latest in the 20.06.X family.
No need to change the "Referencing Fast Downward 20.06" section.
For the changelog section, keep the section title "Changes in Fast Downward 20.06" and the contents, but add the new entries for the bugfix release. Clearly mark which changes belong to 20.06 and which belong to 20.06.1. See ../ChangelogFormat.

FastDownward: ForDevelopers/ReleaseWorkflow (last edited 2023-07-31 19:51:50 by MalteHelmert)

-  ⇤ ← Revision 1 as of 2019-06-06 17:57:24 → 
  Size: 3382
  Editor: FlorianPommerening
  Comment: Initial workflow for making a release
+   ← Revision 39 as of 2022-06-17 19:26:32 → ⇥
  Size: 5499
  Editor: MalteHelmert
  Comment: filename downward.sif => fast-downward.sif
-Deletions are marked like this.
+Additions are marked like this.
 Line 5:
-Let us assume that we want to create the 19.06 release. The steps we'd do are;
+Assuming we want to create the `20.06` release, these are the steps we would follow:
 Line 7:
-. Update to the revision we want to release, e.g., `default`.
+. Make sure that all Github actions are green.
 1. Make sure that you are on the revision you want to release.
 1. Make sure that the list of contributors and copyright years in the `README.md` file are up to date.
 1. 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. 
     1. Replace the section title {{{## Changes since the last release}}} with something like {{{## Fast Downward 20.06}}}.
 1. Make sure that the working directory is clean and that any last-minute changes done following the above steps are commited.
 1. Update version number and create branches, tags and recipe files by running the `prepare-release.sh` script.
-Line 9:
+Line 16:
-hg update default
+./misc/releases/prepare-release.sh 20.06.0
-Line 11:
+Line 18:
-. Collect the changelog information (somehow) and add it to `CHANGES.md`.
 1. Commit the changelog.
    {{{
hg commit -m "Update changelog for release 19.06."
    }}}
 1. Create a branch named `release-19.06`, update the version number, and create a tag named `release-19.06.0`.
    {{{
hg branch release-19.06
hg commit -m "Create branch for release 19.06."
misc/set-version.py 19.06.0
hg commit -m "Update version number to 19.06.0"
hg tag release-19.06.0 -m "Create release 19.06."
    }}}
 1. Back on the default branch, update version number to `19.06.0+`.
    {{{
hg update default
misc/set-version.py 19.06.0+
hg commit -m "Update version number to 19.06.0+"
    }}}
+. Verify the following manually:
    1. The `fast-downward-20.06.0.tar.gz` tarball created in the previous step contains the appropriate files.
    1. Branches and tags were created as expected.
    1. A new commit was created with the right recipe files and version changes.
-Line 32:
+Line 24:
-hg push
+git push --all
git push --tags
-Line 34:
+Line 27:
-. Create the tarball
+. Build the Docker image and push it to the Docker Hub. Note that we build the `20.06` Docker image, not `20.06.0`. Under normal conditions, Docker needs root rights, and the script needs an environment variable that points to a directory containing the !SoPlex archive in the correct version. The actual push to Docker hub needs appropriate credentials. Malte has them; not sure anyone else does. (Please edit if you do.)
-Line 36:
+Line 29:
-hg archive -r release-19.06.0 -X .hg_archival.txt -X .hgignore \
-X .hgtags -X .uncrustify.cfg -X bitbucket-pipelines.yml \
-X experiments/ -X misc/ --type tgz fast-downward-19.06.tar.gz
+sudo DOWNWARD_LP_INSTALLERS=/path/to/dir/with/installer/ ./misc/releases/push-docker.sh 20.06
-Line 40:
+Line 31:
-. Manually verify that the tarball contains the correct files.

 1. Generate the different recipe files for Docker, Singularity and Vagrant.
+. Build the Apptainer (successor to Singularity) image:
-Line 44:
+Line 33:
-misc/release/create-images.py --tag 19.06
+sudo apptainer build fast-downward.sif misc/releases/20.06/Singularity.20.06
-Line 46:
+Line 35:
-. Take the generated Dockerfile, put it into a temporary empty directory, and build it. You can remove the directory immediately afterwards as the docker image is stored in your local registry.
    {{{
# Assuming you are in a temporary directory containing Dockerfile.19.06 only
docker build -t aibasel/downward:19.06 -f Dockerfile.19.06 .
    }}}
 1. Login into the Docker Hub with your credentials (you must be part of the `aibasel` organization!), push the image that we just generated and label it as latest.
    {{{
docker login --username=gfrancesm
docker push aibasel/downward:19.06
docker tag aibasel/downward:19.06 aibasel/downward:latest
docker push aibasel/downward:latest
    }}}
 1. Clean up created container and all unused docker images.
    {{{
docker rmi aibasel/downward:19.06
docker image prune -f
    }}}
 1. Once the Docker image is in the Hub, the Singularity image can be built on the Singularity Hub servers. Add all newly-generated recipe files to your local copy of the [[https://github.com/aibasel/downward|Fast Downward containers repository]].
    {{{
git add 19.06/Dockerfile.19.06
git add 19.06/Singularity.19.06
git add 19.06/Vagrantfile.19.06
ln -fs 19.06/Dockerfile.19.06 latest/Dockerfile
ln -fs 19.06/Singularity.19.06 latest/Singularity
ln -fs 19.06/Vagrantfile.19.06 latest/Vagrantfile
git add latest
git commit -m "Add recipe files for release 19.06."
git push
    }}}
 1. Create a Wiki page for the release. We suggest copying the one from the last [[Releases|release]].
+ Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.0.2. <<BR>>
 Note: From what I understand, Apptainer doesn't actually need the recipe files that we build any more, and one could just build directly from the docker image. If someone is interested in getting rid of the recipes and modernizing the process, please speak to Malte and Florian (unless you're Malte or Florian ;-)). For now, I've left things as they are because it worked.
 1. Test, at minimum:
    * 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
 1. Add a new empty section {{{## Changes since the last release}}} to the changelog to prepare the changelog section for the next release. Commit and push.
 1. Create a Wiki page for the release. We suggest starting from a copy of the page for the [[Releases|last release]].
-Line 79:
+Line 46:
-. Upload the Vagrant file created by the `create-images.py` script as an attachment to the page.
+. Upload the Vagrant filecreated by the `prepare-release.sh` script as an attachment to the page.
    1. Upload the `fast-downward.sif` Apptainer image as an attachment to the page.
-Line 81:
+Line 49:
+. Make sure the necessary acknowledgements and links are included for !SoPlex.
 1. Create a new release on github:
    1. On https://github.com/aibasel/downward/releases click on "Draft new release"
    1. Set `Tag` to `release-20.06.0`, `Release Title` to `20.06`, and `Description` to `For information about this release, please visit the [Fast Downward wiki](https://www.fast-downward.org/Releases/20.06)`.
    1. Click on `Publish Release`
-Line 82:
+Line 55:
+== Bugfix Releases ==

For a bugfix release, the `prepare-release.sh` script must be run while you are at the tip of the existing release branch.
Otherwise, the script transparently handles the differences in the workflow for bugfix releases, so you should be able to apply the above steps with no change, except for the Wiki update.
For a bugfix release such as `20.06.1`, we do not create a new wiki page, but reuse the major release page (20.06). So we do not change [[Releases]] at all, but update [[Releases/20.06]] as follows:

 1. Change the title from `Fast Downward 20.06` to `Fast Downward 20.06.1`.
 1. Add a line like "Fast Downward 20.06.1 was released on July 33, 2020" below the existing line, leaving the old release date information in place.
 1. Update the source tarball link and upload the new tarball. Don't delete the old tarball, just don't link it from anywhere in the page.
 1. No need to update the Docker / Singularity / Vagrantfile links: we will at all times keep one single version of these releases, the latest in the 20.06.X family.
 1. No need to change the "Referencing Fast Downward 20.06" section.
 1. For the changelog section, keep the section title "Changes in Fast Downward 20.06" and the contents, but add the new entries for the bugfix release. Clearly mark which changes belong to 20.06 and which belong to 20.06.1. See [[../ChangelogFormat]].

Wiki

Page

User

Release Workflow

Bugfix Releases