Differences between revisions 36 and 57 (spanning 21 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. Add a new section like ## Fast Downward 20.06 and gather all changes since the last release from the commit messages.
Make sure that the working directory is clean and that any last-minute changes done following the above steps are committed.
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.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. 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 20.06
```
Build the Apptainer (successor to Singularity) image:
- ```
apptainer pull fast-downward.sif docker://aibasel/downward:20.06
```
Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.2.2.
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 (to build the VM with LP solvers, you need an environment variable DOWNWARD_LP_INSTALLERS that points to a directory containing the CPLEX installer in the correct version.)
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 file created by the prepare-release.sh script as an attachment to the page.
5. Create a link in Releases to the page of the new release.
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-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.
Send the same announcement as a message in the Fast Downward Discord server.

Bugfix Releases

$/!\$ It has proven to be error-prone to keep this section in sync with the previous one. The next time we do a bugfix release, we might consider merging the two sections (but it is perhaps too much work to do this preemptively, especially as we might want to simplify these workflows anyway).

The bugfix release workflow is a little different than the workflow for a new release, but it also has a lot in common. The major difference comes from the fact that you need to manually select the issues / fixes that you want to include in (and hence also those that you want to exclude from) the bugfix release. For simplicity of reuse, we repeat all steps here. All provided commands use bugfix 22.06.1 for release 22.06, replace this accordingly for your bugfix release.

Start by checking out the release branch
- ```
git checkout release-22.06
```
For all issue branches that you want to include in the bugfix release, repeat the following steps, starting with the branch that was merged into main the earliest:
1. cherry-pick the merge commit with hash HASH of the issue branch XXXX with
  - ```
  git cherry-pick HASH -m 1
```
2. fix any merge conflicts that might arise (if any merged branches are excluded from the bugfix release, this will likely happen for the first branch in CHANGES.md)
3. commit changes on release branch
  - ```
  git commit -m "[release-22.06] Cherry-picked issueXXXX"
```
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 bugfix release.
2. Add a new section like ## Fast Downward 20.06.1 and gather all changes since the last (bugfix) release from the commit messages.
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 22.06.1
```
Verify the following manually:
1. The fast-downward-22.06.1.tar.gz tarball created in the previous step contains the appropriate files.
2. A tag like 22.06.1 was created on the existing release branch 22.06
3. A new commit was created with the right recipe files and version changes.
Push all changes.
- ```
git push --all
git push --tags
```
Make sure that all Github actions are green. Note that this step comes much later than in the release workflow because you pushed a version of the planner that did not necessarily exist in the repo before (because some commits might have been excluded).
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:
- ```
apptainer pull fast-downward.sif docker://aibasel/downward:20.06
```
Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.2.2.
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
Update the Wiki page of the release (for a bugfix release such as 22.06.1, we do not create a new wiki page, but reuse the major release page 22.06). See the updated Wiki page for [release 22.06](https://www.fast-downward.org/Releases/22.06) for an example.
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 upload the tarball as an attachment to the page.
4. Upload the Vagrant file created by the prepare-release.sh script as an attachment to the page.
Create a new release on github:
1. On https://github.com/aibasel/downward/releases click on "Draft new release"
2. Set Tag to release-22.06.1, Release Title to 22.06.1, and Description to For information about this release, please visit the [Fast Downward wiki](https://www.fast-downward.org/Releases/22.06).
3. Click on Publish Release
Send an announcement e-mail to the Fast Downward list including changelog information.
Send the same announcement as a message in the Fast Downward Discord server.

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

-  ⇤ ← Revision 36 as of 2022-06-17 18:33:21 → 
  Size: 6101
  Editor: MalteHelmert
  Comment: Add note on DockerHub credentials.
+   ← Revision 57 as of 2023-07-31 19:51:50 → ⇥
  Size: 8624
  Editor: MalteHelmert
  Comment: Simplify apptainer-related steps.
-Deletions are marked like this.
+Additions are marked like this.
 Line 12:
-. 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.
+. Add a new section like {{{## Fast Downward 20.06}}} and gather all changes since the last release from the commit messages.
 1. Make sure that the working directory is clean and that any last-minute changes done following the above steps are committed.
 Line 19:
-. The `fast-downward-20.06.0.tar.gz` tarball created in the previous step contains the appropriate files.
+. The `fast-downward-20.06.tar.gz` tarball created in the previous step contains the appropriate files.
 Line 27:
-. 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.)
+. 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. The actual push to Docker hub needs appropriate credentials. Malte has them; not sure anyone else does. (Please edit if you do.)
 Line 29:
-sudo DOWNWARD_LP_INSTALLERS=/path/to/dir/with/installer/ ./misc/releases/push-docker.sh 20.06
+sudo ./misc/releases/push-docker.sh 20.06
 Line 31:
-. /!\ For releases up to 20.06, we built Singularity images on Singularity Hub, but since then Singularity Hub no longer accepts new builds and only remains as an archive of old images. We therefore create Singularity images ourselves. This is futher complicated by Singularity no longer being available on Ubuntu (but there is a new unrelated package called `singularity`) and by Singularity transitioning to a new identity. As of February 2022, the "new" singularity, called Apptainer, only has a 1.0 release candidate and is described as not ready for production. For the 21.12 release, we created a Singularity image manually with `sudo singularity build downward.sif Singularity.21.12` (from the directory containing the recipe file `Singularity.21.12`) and uploaded this manually to the release page. In the future, we can presumably build this directly with Singularity/Apptainer without the recipe file, just using the Docker image on Docker Hub. This is already possible in Singularity 3, but we found that too hard to install for the release process, whereas we had an older Singularity from an older Ubuntu version available. We need to decide how to build and publish Singularity images in the future and update the QuickStart instructions. TODO: Update this step when we do the next release. TODO/later edit: Apptainer now has (at least) a 1.0.2 release, and it includes a deb package for Ubuntu. See https://github.com/apptainer/apptainer/releases. We should update our pages, including the release pages and QuickStart, to refer to Apptainer instead of Singularity (but explaining the name change, at least for some time) and explaining how to install it.
 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.
+. Build the Apptainer (successor to Singularity) image:
    {{{
apptainer pull fast-downward.sif docker://aibasel/downward:20.06
    }}}
 Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.2.2. <<BR>>
 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 (to build the VM with LP solvers, you need an environment variable {{{DOWNWARD_LP_INSTALLERS}}} that points to a directory containing the CPLEX installer in the correct version.)
-Line 39:
+Line 46:
-. Make sure the necessary acknowledgements and links are included for !SoPlex.
-Line 41:
+Line 47:
-. On https://github.com/aibasel/downward/releases click on "Draft new release"
+. On https://github.com/aibasel/downward/releases click on "Draft a new release"
-Line 45:
+Line 51:
+. Send the same announcement as a message in the Fast Downward Discord server.
-Line 49:
+Line 56:
-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:
+/!\ It has proven to be error-prone to keep this section in sync with the previous one. The next time we do a bugfix release, we might consider merging the two sections (but it is perhaps too much work to do this preemptively, especially as we might want to simplify these workflows anyway).
-Line 53:
+Line 58:
-. 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]].
+The bugfix release workflow is a little different than the workflow for a new release, but it also has a lot in common. The major difference comes from the fact that you need to manually select the issues / fixes that you want to include in (and hence also those that you want to exclude from) the bugfix release.  For simplicity of reuse, we repeat all steps here. All provided commands use bugfix 22.06.1 for release 22.06, replace this accordingly for your bugfix release.

 1. Start by checking out the release branch
    {{{
git checkout release-22.06
    }}}
 1. For all issue branches that you want to include in the bugfix release, repeat the following steps, starting with the branch that was merged into main the earliest:
   1. cherry-pick the merge commit with hash HASH of the issue branch XXXX with
    {{{
git cherry-pick HASH -m 1
    }}}
   1. fix any merge conflicts that might arise (if any merged branches are excluded from the bugfix release, this will likely happen for the first branch in CHANGES.md)
   1. commit changes on release branch 
    {{{
git commit -m "[release-22.06] Cherry-picked issueXXXX"
    }}}
 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 bugfix release. 
     1. Add a new section like {{{## Fast Downward 20.06.1}}} and gather all changes since the last (bugfix) release from the commit messages.
 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.
    {{{
./misc/releases/prepare-release.sh 22.06.1
    }}}
 1. Verify the following manually:
    1. The `fast-downward-22.06.1.tar.gz` tarball created in the previous step contains the appropriate files.
    1. A tag like `22.06.1` was created on the existing release branch `22.06`
    1. A new commit was created with the right recipe files and version changes.
 1. Push all changes.
    {{{
git push --all
git push --tags
    }}}
 1. Make sure that all Github actions are green. Note that this step comes much later than in the release workflow because you pushed a version of the planner that did not necessarily exist in the repo before (because some commits might have been excluded).
 1. 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
    }}}
 1. Build the Apptainer (successor to Singularity) image:
    {{{
apptainer pull fast-downward.sif docker://aibasel/downward:20.06
    }}}
 Note: Ubuntu (*.deb) packages for Apptainer are available here: https://github.com/apptainer/apptainer/releases. Tested with Apptainer 1.2.2. <<BR>>
 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. Update the Wiki page of the release (for a bugfix release such as `22.06.1`, we do not create a new wiki page, but reuse the major release page `22.06`). See the updated Wiki page for [release 22.06](https://www.fast-downward.org/Releases/22.06) for an example.
    1. Adjust the date and mention the bugfix release version name.
    1. Update the changelog.
    1. Update the name of the tarball (it should include the bugfix number) and upload the tarball as an attachment to the page. 
    1. Upload the Vagrant file created by the prepare-release.sh script as an attachment to the page.
 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-22.06.1`, `Release Title` to `22.06.1`, and `Description` to `For information about this release, please visit the [Fast Downward wiki](https://www.fast-downward.org/Releases/22.06)`.
    1. Click on `Publish Release`
 1. Send an announcement e-mail to the Fast Downward list including changelog information.
 1. Send the same announcement as a message in the Fast Downward Discord server.

Wiki

Page

User

Release Workflow

Bugfix Releases