Cutting a release

Major version

This document details the instructions for cutting a new release of Halide.

Let Halide_VERSION be the version to be released. Similarly let Halide_VERSION_{MAJOR,MINOR,PATCH} refer to the major, minor, and patch versions. Since this a major version release, Halide_VERSION_MINOR and Halide_VERSION_PATCH should be 0. It might even be helpful to create environment variables while we're doing this, for example:

$ export Halide_VERSION="19.0.0"
$ export Halide_VERSION_MAJOR="${Halide_VERSION%%.*}"

Step 1: Create a new release branch

First, check-out the commit that will constitute the release. Ideally, this will be the HEAD of main, but might come earlier in the history if the release is delayed.

Create a branch off of this commit named release/${Halide_VERSION_MAJOR}.x. Push it.

Save the release commit to your environment by running:

$ export COMMIT="$(git rev-parse HEAD)"

Step 2: Bump the version on main

Switch back to main and run tbump with the next major version:

$ git checkout main
$ export Halide_NEXT_VERSION="$((Halide_VERSION_MAJOR + 1)).0.0"
$ tbump "${Halide_NEXT_VERSION}"
:: Bumping from 19.0.0 to 20.0.0
=> Would update current version in pyproject.toml
- pyproject.toml:107 current = "19.0.0"
+ pyproject.toml:107 current = "20.0.0"
=> Would patch these files
- CMakeLists.txt:19 VERSION 19.0.0
+ CMakeLists.txt:19 VERSION 20.0.0
- python_bindings/CMakeLists.txt:2 project(Halide_Python VERSION 19.0.0)
+ python_bindings/CMakeLists.txt:2 project(Halide_Python VERSION 20.0.0)
- vcpkg.json:3 "version": "19.0.0",
+ vcpkg.json:3 "version": "20.0.0",
- src/runtime/HalideRuntime.h:26 #define HALIDE_VERSION_MAJOR 19
+ src/runtime/HalideRuntime.h:26 #define HALIDE_VERSION_MAJOR 20
- src/runtime/HalideRuntime.h:27 #define HALIDE_VERSION_MINOR 0
+ src/runtime/HalideRuntime.h:27 #define HALIDE_VERSION_MINOR 0
- src/runtime/HalideRuntime.h:28 #define HALIDE_VERSION_PATCH 0
+ src/runtime/HalideRuntime.h:28 #define HALIDE_VERSION_PATCH 0
=> Would run these git commands
$ git add --update
$ git commit --message Bump version to 20.0.0
$ git tag --annotate --message v20.0.0.dev0 v20.0.0.dev0
$ git push --atomic origin main v20.0.0.dev0
:: Looking good? (y/N)
>

This will require bypassing branch protection rules. This is necessary because the tag tbump creates must be pushed atomically with the commit.

Switch back to the release branch:

$ git checkout -

Step 3: Update the buildbot master

The buildbot master currently has a hard-coded list of Halide and LLVM versions. These need to be updated for the new release. See halide/build_bot#191 for an example. Get that merged and restart the build-master (currently only @steven-johnson can do this).

It might be necessary to force-schedule the packaging builds.

Step 4: Write a change-log for the release

Look through the git history for a list of changes and write a change-log while you wait for the buildbots to run.

A useful command is:

$ git log --no-merges --oneline ${PREVIOUS_RELEASE}..${COMMIT}

Step 5: Get the binaries from the buildbots

Some time after updating the buildbot master, there should be new binaries ready for Halide. You should expect to see:

Halide-${Halide_VERSION}-arm-32-linux-${COMMIT}
Halide-${Halide_VERSION}-arm-64-linux-${COMMIT}
Halide-${Halide_VERSION}-arm-64-osx-${COMMIT}
Halide-${Halide_VERSION}-x86-32-linux-${COMMIT}
Halide-${Halide_VERSION}-x86-32-windows-${COMMIT}
Halide-${Halide_VERSION}-x86-64-linux-${COMMIT}
Halide-${Halide_VERSION}-x86-64-osx-${COMMIT}
Halide-${Halide_VERSION}-x86-64-windows-${COMMIT}

Download these via

$ wget -nd --directory-prefix="${COMMIT}" -r --no-parent --no-clobber -A "*${COMMIT}*" https://buildbot.halide-lang.org/

This will save all eight archives to a directory named $COMMIT.

Step 6: Create a new GitHub release

Begin drafting a new release here: https://github.com/halide/Halide/releases/new

The tag should be v${Halide_VERSION}. Paste in the change-log you wrote in Step 4 and upload the binaries you got in Step 5. Now you're set!

Step 7: Update the tutorial

In the Halide repo, sync to ${COMMIT}, then:

make distrib -j32 && cd tutorial/figures && bash ./generate_output_snippets.sh

This script requires gdb, so running on Linux is much easier than macOS. Also note you must have functioning OpenCL installed. (Don't forget to use the correct version of LLVM!)

In the halide.github.com repo:

cd tutorials/ && bash ./gen_tutorials.sh $(ls /path/to/halide/tutorial/*.{cpp,sh})

Again, this is likely to require running from a Linux box. You must have highlight installed.

Sanity-check the tutorials by opening tutorials/tutorial_introduction.html in a browser

Finally, commit the result:

git commit -am "Regenerate tutorials for Halide ${Halide_VERSION}"

TODO: convert these steps to CMake.

Step 8: Update documentation

Note

TODO: this should be automated on GitHub Actions

First, build the documentation using CMake:

$ cmake --preset macOS-vcpkg -DWITH_DOCS=YES  # for example
$ cmake --build build/macOS-vcpkg --target doc

Now switch to the the halide.github.com repo and run:

$ git rm -r docs
$ cp -r ../Halide/build/macOS-vcpkg/doc/html/ docs
$ git add docs

Sanity check the docs and tutorials by opening docs/index.html in a browser

Finally, commit the result:

$ git commit -am "Regenerate documentation for Halide ${Halide_VERSION}"

Step 9: Let people know!

Send an email to [email protected]. Also let our package maintainer partners know about the changes. We keep an open issue tracking this here: #4660

Minor or patch version

Step 0: Prepare the Backports branch

Apply all fixes in a corresponding backports/${Halide_VERSION_MAJOR}.x branch. If this branch doesn't exist yet for a new release, create it by forking from the corresponding release/${Halide_VERSION_MAJOR}.x branch. Push it.

If the branch does exist, it should be current with the last point release.

Step 1: Cherry-pick fixes from main into the Backports branch

Cherry-pick fixes from main into this branch that have passed Q/A. Be sure to use the -x flag for git cherry-pick -x to include the relevant change-set in the commit log. Push these and create a PR to merge them into the backports branch. Don't squash the commit logs during the PR to make it easier to backtrack!

Step 2: Bump the point release

Update the version in the repo to the next point-release. If the changes are merely bug-fixes without any interface changes or new features, increment the Halide_VERSION_PATCH number. If the changes are significant and alter behavior or may be incompatible with a previous point release, increment the Halide_VERSION_MINOR and reset the Halide_VERSION_PATCH back to zero.

In the main repo, make sure README.md has the new version number. Make sure this has happened some time before the release commit.

Double check that the version number in CMakeLists.txt is correct, too! This will label the build products accordingly.

Open a pull request to merge these changes into the release branch (eg #5734). Don't squash the commit logs during the PR to make it easier to backtrack!

As part of the pull request, the build bots will create the binary build products using the version label updated in the CMakeLists.txt. After all changes are approved and the build and tests succeed, these binaries can be used for the release notes (steps 3-6).

Steps 3, 4, 5, 6:

Same as above for a new major release. You can skip step 3 because no LLVM versions were changed. Docs and tutorials should only be regenerated if there are in fact documentation changes.

Step 7: Let people know!