Cutting a release

When we “cut” a release, we begin the process of making a release. (This is not to be confused with publishing a release, which is the last step.) After a release is cut, we can perform manual QA testing and polish any remaining small changes.

1. Set a VERSION variable in your shell

   Run this command to set a local variable within your shell to the version number of the release you’re making.

   VERSION=1.2.3 # ⚠️ CUSTOMIZE THIS
   

   Note

   Do not prefix the version with v.

2. Cut the release branch

   Run these commands from within the repo, locally.

   git checkout develop
   git pull origin develop
   git checkout -b release-$VERSION
   

3. Notify team that release branch is cut

   This is important because engineers will need to know to target the release branch with any subsequent PRs intended for the release.

4. Update version numbers

   sed -i "s/^__version__ =.*\$/__version__ = \"$VERSION\"/" mathesar/__init__.py
   sed -i "s/^  mathesar_version:.*\$/  mathesar_version: $VERSION/" docs/mkdocs.yml
   git commit -a -m "Update version numbers to $VERSION"
   

5. Create the release PR

   git push -u origin release-$VERSION
   gh pr create -d -B master -m "v$VERSION" -t "Release $VERSION" -b ""
   

6. Publish Docker images for QA

   1. Log in to DockerHub

      docker login
      

      (Use your personal Docker credentials. Your personal Docker account will need to be a member of our mathesar Docker org.)

   2. Locally clone the repo into a clean directory and go there.

      REPO_DIR=$(pwd)
      CLEAN_REPO_DIR=$(mktemp -d)
      cd $CLEAN_REPO_DIR
      git clone -b release-$VERSION --single-branch --no-tags "$REPO_DIR" .
      

      (This ensures that files which are ignored by git don’t end up in the Docker image.)

   3. Build and push images to DockerHub

      docker buildx build \
        -t mathesar/mathesar-caddy:$VERSION \
        --builder=cloud-mathesar-release-builder \
        --platform=linux/amd64,linux/arm64 \
        --push \
        -f Dockerfile.caddy .
      
      docker buildx build \
        -t mathesar/mathesar:$VERSION \
        --builder=cloud-mathesar-release-builder \
        --platform=linux/amd64,linux/arm64 \
        --push .
      

      (These images are intentionally not tagged as latest — that will happen during publication.)

      If you have trouble running these commands, make sure you’ve run the prerequisite setup steps.

   4. Clean up

      cd "$REPO_DIR"
      rm -rf $CLEAN_REPO_DIR
      docker logout
      

7. Create a pre-release for QA

   1. Create and push a tag on GitHub with the release version.

      git checkout "release-$VERSION"
      git pull
      git tag "$VERSION"
      git push origin "$VERSION"
      

   2. GH will automatically create a draft release containing the installation assets for this tag. This will take a few minutes.

   3. Update the release name & description to make it clear that it’s a testing release.

   4. Publish this draft release as a Pre-release via the GitHub UI.

      Do not set the release as latest

      • Ensure that the checkbox mentioning latest is not checked.
      • Only set the release as a Pre-release.
      • Double check this before publishing.