Release process

This page documents the steps to follow to make a new release of QMCPACK. The examples are given for the 3.12.0 release.

1. Make a fresh clone of the repo and create a release candidate branch labeled rc_Mmp where Mmp are digits following semantic versioning.

git clone https://github.com/QMCPACK/qmcpack.git
cd qmcpack
git branch rc_3120
git checkout rc_3120

2. Update the VERSION numbers in the project section of qmcpack/CMakeLists.txt for the new release, e.g. 3.12.0
3. Update qmcpack/CHANGELOG.md by replacing the unreleased section with the new version and release date. Update the notes section to recommend the update to all users (if appropriate) and note any major headline items such as backwards incompatibility. Use github_changelog_generator -u QMCPACK -p qmcpack -o AUTOCHANGELOG.md -t YOUR_GITHUB_TOKEN --since-tag v3.11.0 to automatically generate a starting point. It will need substantial editing.

git add qmcpack/CMakeLists.txt qmcpack/CHANGELOG.md
git commit -m "Increase version number, update release notes"
git push origin rc_3120

4. On GitHub, make a pull request into the main branch from the rc.
5. Ensure CI tests run and pass.
6. Make an independent download of the proposed merged PR.
7. Verify code configures and builds on at least one system. Be sure to do this on a clean, freshly cloned repo.
8. Run non-long tests, confirm version reports correctly. e.g. ctest -VV -E long. Confirm the results are appropriately similar to the last nightly and weekly test results.
9. Push any needed fixes to the rc and repeat the tests.
10. Add notes on the test status to the PR.
11. Request reviewer / other PR approver approves the merge. At least one review is required to merge to main. Reviewer needs to check the updated version number and CHANGELOG.
12. Merge the PR.
13. Create a new release using the release tool on GitHub. Link to the CHANGELOG.md in the release notes. The GitHub link can be copied & updated from previous release.
14. Issue a PR back to develop from main to update with the new version number and any other updates made to the rc.
15. Once the PR is merged to develop, update the QMCPACK_VERSION_PATCH version to 9 in CMakeLists.txt in the develop branch to indicate it is the development version.
16. Delete the rc branch.
17. Verify readthedocs is seeing the new release and update readthedocs configuration if needed.
18. Update qmcpack.org via https://qmcpack.org/user and by creating a page of type "Release" with title similar to "QMCPACK Release v3.5.0 - 2018-08-02". The page type is required for https://www.qmcpack.org/releases to update automatically. Also check the documentation pages.
19. Announce the release on google groups and QMCPACK.org.