BornAgain ≻ git-develop ≻ Documentation ≻ Developers' corner ≻ Prepare a release

Prepare a release

This procedure is for maintainers. It requires write access to the BornAgain, bornagain-www, and mlz/homebrew repositories, PyPI and Zenodo tokens, and the www account on the web server.

Test phase

  • Decide whether it’s a major, minor, or patch increment, and set the MAJOR.MINOR.PATCH version number in CMakeLists.txt
  • Declare feature freeze
  • Release new versions of library dependencies (heinz, ff) if they have changed
  • For a major or minor release, create rMAJOR.MINOR from develop. For a patch release, use the existing release branch
  • Before pushing the branch, set release_number to MAJOR.MINOR.PATCH and baseURL to https://bornagainproject.org/MAJOR.MINOR in hugo/hugo.toml. CI publishes the branch’s documentation on every push
  • Update CHANGELOG
  • Test the release candidate
    • check that the CI wheel jobs succeed
    • install wheels and the Homebrew formula according to the webdocs
    • run Python scripts
  • Start a new branch in bornagain-www, and write the release letter (content/news/release-*.md)

Finalize release

  • Finalize CHANGELOG through a merge request to the release branch
  • After merging, tag the release as vMAJOR.MINOR.PATCH and push the tag

Finalize the bornagain-www release branch:

  • Finalize release letter
  • Update content/documentation.md
  • Update static/js/version_switch.js
  • In hugo.toml, update version_mmp for the release and version_mm for the documentation path
  • Hold back MR until everything else is ready

Upload wheels

CI builds the release wheels when the git tag is pushed. The macOS release is distributed through Homebrew.

Wait for the tag pipeline’s wheel jobs to finish successfully before uploading.

Install and authenticate glab and twine, and make sure unzip is available. Then run from the BornAgain checkout of the release tag:

export TWINE_TOKEN="your-PyPI-API-token"
./scripts/pypi-push

The script fetches all wheel artifacts from the CI pipeline for the checked-out tag, lists them with sizes, and asks for confirmation before uploading. This creates a new version on PyPI and is irreversible.

Before confirming, verify the tag and pipeline printed by the script.

Zenodo deposit

Use the zenodo-push script provided by the scg-intern repository. Run it from the BornAgain checkout of the release tag:

export ZENODO_TOKEN="your-Zenodo-API-token"
zenodo-push

The script uses BornAgain’s .zenodo configuration, archives the tagged commit, uploads it to Zenodo, and publishes the record.

Publish

  • Create release in Jugit

  • Add the versioned BornAgain formula to mlz/homebrew, pin the BornAgain and library dependency tags and revisions, and run brew install and brew test for the formula

  • Wait for the release branch’s versiondocs job to succeed. It builds the documentation, publishes it, and creates the /MAJOR.MINOR/ link

  • Check the published documentation at https://bornagainproject.org/MAJOR.MINOR/

  • As www on scg3, point latest to the checked version:

    cd ~/www/ba/public
ln -sfn MAJOR.MINOR latest

  • Merge the bornagain-www release branch to publish the release letter and update the main website’s version links

  • Inform users

    • Mail to BornAgain mailing list
    • For major milestones, mail to external mailing lists (neutron, sa_scat [unsigned mails only!])
    • Update “Latest” section on computing.mlz-garching.de

Continue development

  • Merge changes back into develop
    • fork new feature branch from develop
    • merge release branch
    • restore “git-develop” in hugo/hugo.toml
    • update version number in CMakeLists.txt
    • create MR against develop