EXAUQ‐Toolbox Release Procedure - EXA-UQ/EXAUQ-Toolbox GitHub Wiki

This document outlines the step-by-step process for creating and publishing new releases of the EXAUQ-Toolbox. It covers the complete workflow from preparation to post-release activities, ensuring consistent and reliable versioning. Follow these instructions to properly update the codebase, maintain documentation, manage branch protections, and synchronize development branches after each release. This procedure helps maintain code quality and ensures all team members follow standardized release practices.

1. Ensure dev is Up to Date

Before starting, make sure your dev branch is fully updated:

git checkout dev
git pull origin dev

Run tests to ensure everything is stable:

# Run all tests in the /tests/ directory
python -m unittest discover -s tests

Check that the notebooks build correctly:

python scripts/build_notebooks.py

Check that the documentation builds correctly:

mkdocs build

Preview the documentation locally to verify it works:

mkdocs serve

2. Create a Release Branch

Create a new release branch from dev:

git checkout -b release-vX.Y.Z

Bump the version number in pyproject.toml:

[tool.poetry]
version = "X.Y.Z"  # Update to the new version

Also update the version and release date in CITATION.cff:

version: "vX.Y.Z"
date-released: YYYY-MM-DD

Note:
Keep the DOI as the concept DOI (10.5281/zenodo.15005642) so it always points to the latest version — no need to change this per release.

Then commit and push:

git add pyproject.toml CITATION.cff
git commit -m "Bump version to vX.Y.Z and update CITATION.cff"
git push origin release-vX.Y.Z

3. Open a Pull Request to main

  1. Go to the EXAUQ-Toolbox repository on GitHub.
  2. Click "New Pull Request".
  3. Set the following:
    • Base branch: main
    • Compare branch: release-vX.Y.Z
    • Title: Release vX.Y.Z
    • Description: Add details on the changes included in this release.
  4. Request reviews from the relevant team members.
  5. Click "Create Pull Request".

4. Reviews and CI

  • Get review approval.
  • Wait for CI tests to pass.

5. Unlock main and gh-pages Branches

GitHub branch protection prevents direct updates, so temporarily adjust the protection settings to allow the release process to complete.

  1. Go to the EXAUQ-Toolbox repository → Settings → Code and Automation → Branches.
  2. Under Branch Protection Rules, click Edit for the main branch:
    • Uncheck Lock branch.
    • Click Save changes.
  3. Repeat the above steps for the gh-pages branch, but also:
    • Check Allow force pushes.
    • Select Everyone as the permission level for force pushes (unless GitHub Actions or a specific user/group should have restricted access).
  4. Click Save changes.

This allows the "Documentation Upload" workflow to force push updates to gh-pages while keeping branch protections in place.

6. Merge the PR, Check, and Relock Branches

  1. Merge the PR into main using the approved GitHub workflow.
  2. Wait for successful completion of the "Documentation Upload" workflow.
  3. Verify the documentation has been successfully deployed to GitHub Pages:
    📌 EXAUQ-Toolbox Documentation
  4. Relock the main and gh-pages branches following the same steps as in Step 5.

7. Tag the Release

Create a GitHub release, which also generates a version tag:

  1. Go to GitHub Releases.
  2. Click "Draft a new release".
  3. In the Tag version field, enter vX.Y.Z.
  4. Select the latest commit from main as the tag source.
  5. Add release notes describing major changes.
  6. Click "Publish Release".

8. Sync dev with main

After releasing a new version, ensure the dev branch is updated with the latest changes from main.

Since dev is a protected branch and can only be updated via a pull request, follow these steps:

1. Create a Sync Branch

Branch off main and merge the latest dev changes into it:

git checkout main
git pull origin main  # Ensure local main is up to date

git checkout -b sync-dev-with-main
git merge origin/dev  # Merge latest dev changes into this branch

2. Resolve Merge Conflicts (If Any)

If there are conflicts, resolve them manually, then commit:

git add .
git commit -m "Resolve merge conflicts between main and dev"

3. Push the Sync Branch and Open a PR

Push the branch and open a pull request to update dev:

git push origin sync-dev-with-main
  1. Go to GitHub > EXAUQ-Toolbox repository.
  2. Click "New Pull Request".
  3. Set:
    • Base branch: dev
    • Compare branch: sync-dev-with-main
    • Title: Sync main with dev after release vX.Y.Z
    • Description: "Merging the latest release changes from main into dev to keep development up to date."
  4. Request reviews and approval.
  5. Click "Create Pull Request".

4. Merge the PR into dev

  • Wait for CI checks to pass.
  • Once approved, merge the PR into dev.

5. Delete the Sync Branch

After merging, delete the sync branch:

git branch -d sync-dev-with-main
git push origin --delete sync-dev-with-main

Now dev is fully updated with the latest changes from main, ensuring all development continues from the latest release. 🚀

✅ Done!

The release is now complete, and the EXAUQ-Toolbox is successfully updated. 🚀