Skip to content

Release checklist

Jump to bottom
Jean-Noël Grad edited this page May 22, 2024 · 3 revisions

Create the release candidate:

  • Create a new branch in a fork of the espressomd/espresso repository
  • Cherry-pick commits with git cherry-pick <commit> and pull requests with git cherry-pick -m 1 <branch>
  • Open a draft PR of the release candidate against the python branch (major or minor release) or against the corresponding minor branch (bugfix release)

May change repository

For new-features releases:

  • Update CI containers to recent version of libs and distributions
    • There should be CI for a current and a previous or LTS release
    • Still older distribution releases can be removed from CI
    • There should be containers for the current and previous CUDA version
  • Check Python modules version in /requirements.txt
  • Check CMake version in /CMakeLists.txt
  • Check contributors in /AUTHORS
    • Relevant script: /maintainer/find_potentially_missing_authors.sh
    • The result has to be checked manually, since some people commit using different names/addresses
    • With a mailmap, you can simply do git shortlog -se 4.1.2..4.1.3rc
    • Update names of core developers if applicable

For all releases

  • Update /NEWS file to include release notes for current release
  • Spell and grammar check comments and docs
  • Check and fix copyright headers
  • Run CI jobs that are set to manual
  • Push the release
    • Fetch the release candidate
    • Update version number from X.Y-dev to X.Y.Z in /CMakeLists.txt
    • Push to the relevant branch
    • In the CI of that branch, run all jobs
    • Workflow:
      • Major release: push to new branch "X.0" 
        git checkout -b 4.0 4.0rc
vi CMakeLists.txt
vi src/config/version.hpp.in
git add CMakeLists.txt src/config/version.hpp.in
git commit -S -m 'Update version number to 4.0'
git verify-commit HEAD
git push upstream 4.0
      • Minor release: push to new branch "X.Y" 
        git checkout -b 4.1 4.1rc
vi CMakeLists.txt
vi src/config/version.hpp.in
git add CMakeLists.txt src/config/version.hpp.in
git commit -S -m 'Update version number to 4.1'
git verify-commit HEAD
git push upstream 4.1
      • Bugfix release: push to old branch "X.Y" 
        git checkout 4.1.2rc
vi CMakeLists.txt
git add CMakeLists.txt
git commit -S -m 'Update version number to 4.1.2'
git verify-commit HEAD
git fetch upstream 4.1
git push upstream 4.1.2rc:4.1
    • Relevant thread: #2585
  • Make tarball
    • Create tarball 
      release="4.1.2"
tarball="espresso-${release}.tar.gz"
# fetch the bash script
cd /work/jgrad/git
mkdir git-archive-all
git clone https://github.com/meitar/git-archive-all.sh.git git-archive-all
# tar the release branch
cd /work/jgrad/git/espresso-fork
git fetch upstream ${release}
git checkout ${release}
bash ../git-archive-all/git-archive-all.sh --format tar.gz --prefix "espresso/" ${tarball}
    • Manually unpack tarball, configure with maxset and test installation + documentation 
      tar xfz ${tarball}
cd espresso
mkdir build
cd build
cp ../maintainer/configs/maxset.hpp myconfig.hpp
rm -rf /tmp/espresso-unit-tests
cmake .. -D ESPRESSO_BUILD_WITH_CUDA=ON -D ESPRESSO_BUILD_WITH_HDF5=ON \
    -D ESPRESSO_BUILD_WITH_STOKESIAN_DYNAMICS=ON -D ESPRESSO_BUILD_WITH_SCAFACOS=ON \
    -D CMAKE_INSTALL_PREFIX=/tmp/espresso-unit-tests -D ESPRESSO_CTEST_ARGS=-j$(nproc)
make -j $(nproc)
make -j $(nproc) check_unit_tests
make -j $(nproc) check_python
make -j $(nproc) check_tutorials
make -j $(nproc) check_samples
make -j $(nproc) check_benchmarks
make check_cmake_install
make doxygen
make -j $(nproc) sphinx
user_guide_html=$(realpath doc/sphinx/html)
echo -e '\n\nraise ImportError("")' >> src/python/espressomd/visualization.py
make -j 3 tutorials_html
cd doc/tutorials
mkdir html
python3 ../../../maintainer/CI/deploy_tutorials.py
rsync -a --files-from=deploy_list.txt ./ html
jupyter_html=$(realpath html)
make -j $(nproc) check_utils
    • Sign tarball 
      gpg --output ${tarball}.sig --detach-sig ${tarball}
gpg --verify ${tarball}.sig ${tarball}

No changes after this

  • Tag release and upload tarball+signature using Draft a new release
  • Deploy static documentation to the website
    • In a local fork of espressomd/espressomd.github.io, do: 
      git checkout landing_page
sed -i -r "s/latest_release: [0-9\.]+/latest_release: ${release}/" metadata.yml
git add metadata.yml
git commit -m "Update to release ${release}"
cp -r ${user_guide_html} doc${release}
cp -r ${jupyter_html} tutorials${release}
rm doc${release}/.buildinfo
echo -e '\n/* hide todo notes */\ndiv.admonition-todo {\n    display: none;\n}' >> doc${release}/_static/custom.css
python3 tutorials.py
mv tutorials.md tutorials${release}.md
git checkout releases
git add doc${release} tutorials${release}.md tutorials${release}
git commit -m "Add ${release} user guide and tutorials"
git push origin releases:releases
git push origin landing_page:landing_page
  • Close the corresponding milestone (milestones)
  • Update website using the CMS
  • Post release notes to the users mailing list (espressomd-users@nongnu.org)
  • Update the python branch
    • Port improvements from the release into the python branch: release notes, grammar/spell checking, new authors, etc.
    • Update version number from X.Y-dev to X.Y+1-dev in /CMakeLists.txt and X.Y+1 in /src/config/version.hpp.in
Clone this wiki locally