From e567e4cdd68e544fbd2bdd40de01580f31a015fc Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sun, 2 Feb 2025 04:41:32 -0500 Subject: [PATCH] update notes on release processing steps --- .github/release_steps.md | 171 ++++++++++++++++++++++++++------------- 1 file changed, 117 insertions(+), 54 deletions(-) diff --git a/.github/release_steps.md b/.github/release_steps.md index 15ddd59768..660b285d15 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -1,42 +1,54 @@ # LAMMPS Release Steps -The following notes chronicle the current steps for preparing and publishing LAMMPS releases. For -definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the -LAMMPS manual](https://docs.lammps.org/Manual_version.html). +The following notes chronicle the current steps for preparing and +publishing LAMMPS releases. For definitions of LAMMPS versions and +releases mean, please refer to [the corresponding section in the LAMMPS +manual](https://docs.lammps.org/Manual_version.html). ## LAMMPS Feature Release -A LAMMPS feature release is currently prepared after about 500 to 750 commits to the 'develop' -branch or after a period of four weeks up to two months. This is not a fixed rule, though, since -external circumstances can cause delays in preparing a release, or pull requests that are desired to -be merged for the release are not yet completed. +A LAMMPS feature release is currently prepared after about 500 to 750 +commits to the 'develop' branch or after a period of four weeks up to +two months. This is not a fixed rule, though, since external +circumstances can cause delays in preparing a release, or pull requests +that are desired to be merged for the release are not yet completed. ### Preparing a 'next\_release' branch Create a 'next\_release' branch off 'develop' and make the following changes: -- set the LAMMPS\_VERSION define to the planned release date in src/version.h in the format - "D Mmm YYYY" or "DD Mmm YYYY" +- set the LAMMPS\_VERSION define to the planned release date in + src/version.h in the format "D Mmm YYYY" or "DD Mmm YYYY" - remove the LAMMPS\_UPDATE define in src/version.h - update the release date in doc/lammps.1 -- update all TBD arguments for ..versionadded::, ..versionchanged:: ..deprecated:: to the - planned release date in the format "DMmmYYYY" or "DDMmmYYYY" -- check release notes for merged new features and check if ..versionadded:: or ..versionchanged:: - are missing and need to be added -Submit this pull request, rebase if needed. This is the last pull request merged for the release -and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes). +- update all TBD arguments for ..versionadded::, ..versionchanged:: + ..deprecated:: to the planned release date in the format "DMmmYYYY" or + "DDMmmYYYY" +- check release notes for merged new features and check if + ..versionadded:: or ..versionchanged:: are missing and need to be + added -This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a -bugfix pull request should be created and merged to clear all tests. +Submit this pull request, rebase if needed. This is the last pull +request merged for the release and should not contain any other +changes. (Exceptions: this document, last minute trivial(!) changes). + +This PR shall not be merged before **all** pending tests have completed +and cleared. We currently use a mix of automated tests running on +either Temple's Jenkins cluster or GitHub workflows. Those include time +consuming tests not run on pull requests. If needed, a bugfix pull +request should be created and merged to clear all tests. ### Create release on GitHub -When all pending pull requests for the release are merged and have cleared testing, the -'next\_release' branch is merged into 'develop'. +When all pending pull requests for the release are merged and have +cleared testing, the 'next\_release' branch is merged into 'develop'. -Check out 'develop' locally, pull the latest changes, merge them into 'release', apply a suitable -release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally -push everything back to GitHub. Example: +Check out or update the 'develop' branch locally, pull the latest +changes, merge them into 'release' with a fast forward(!) merge, and +apply a suitable release tag (for historical reasons the tag starts with +"patch_" followed by the date, and finally push everything back to +GitHub. There should be no commits made to 'release' but only +fast forward merges. Example: ``` git checkout develop @@ -48,58 +60,109 @@ git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 git push git@github.com:lammps/lammps.git --tags develop release ``` -Go to https://github.com/lammps/lammps/releases and create a new (draft) release page or check the -existing draft for any necessary changes from pull requests that were merged but are not listed. -Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of -the list and select the "Set as pre-release" checkbox. The "Set as the latest release" button is +Applying this tag will trigger two actions on the Temple Jenkins cluster: +- The online manual at https://docs.lammps.org/ will be updated to the + state of the 'release' branch. Merges to the 'develop' branch will + trigger updating https://docs.lammps.org/latest/ so by reviewing the + version of the manual under the "latest" URL, it is possible to preview + what the updated release documentation will look like. +- A downloadable tar archive of the LAMMPS distribution that includes the + html format documentation and a PDF of the manual will be created and + uploaded to the download server at https://download.lammps.org/tars + Note that the file is added, but the `index.html` file is not updated, + so it is not yet publicly visible. + +Go to https://github.com/lammps/lammps/releases and create a new (draft) +release page with a summary of all the changes included and references +to the pull requests they were merged from or check the existing draft +for any necessary changes from pull requests that were merged but are +not listed. Then select the applied tag for the release in the "Choose +a tag" dropdown list. Go to the bottom of the list and select the "Set +as pre-release" checkbox. The "Set as the latest release" button is reserved for stable releases and updates to them. -If everything is in order, you can click on the "Publish release" button. Otherwise, click on "Save -draft" and finish pending tasks until you can return to edit the release page and publish it. +If everything is in order, you can click on the "Publish release" +button. Otherwise, click on "Save draft" and finish pending tasks until +you can return to edit the release page and publish it. -### Update download website, prepare pre-compiled packages, update packages to GitHub +### Prepare pre-compiled packages, update packages to GitHub -Publishing the release on GitHub will trigger the Temple Jenkins cluster to update -the https://docs.lammps.org/ website with the documentation for the new feature release -and it will create a tarball for download (which contains the translated manual). +Build a fully static LAMMPS installation using a musl-libc +cross-compiler, install into a lammps-static folder, and create a +tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a +corresponding date with a future release) from the lammps-static folder. +A suitable build environment is provided with the +https://download.lammps.org/static/fedora37_musl.sif container image. -Build a fully static LAMMPS installation using a musl-libc cross-compiler, install into a -lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a -corresponding date with a future release) from the lammps-static folder and upload it to GitHub -with: - -``` -gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz +``` sh +wget https://download.lammps.org/static/fedora37_musl.sif +apptainer shell fedora37_musl.sif +git clone -b release --depth 10 https://github.com/lammps/lammps.git lammps-release +cmake -S lammps-release/cmake -B build-release -D CMAKE_INSTALL_PREFIX=$PWD/lammps-static -D CMAKE_TOOLCHAIN_FILE=/usr/musl/share/cmake/linux-musl.cmake -C lammps-release/cmake/presets/most.cmake -C lammps-release/cmake/presets/kokkos-openmp.cmake -D DOWNLOAD_POTENTIALS=OFF -D BUILD_MPI=OFF -D BUILD_TESTING=OFF -D CMAKE_BUILD_TYPE=Release -D PKG_ATC=ON -D PKG_AWPMD=ON -D PKG_MANIFOLD=ON -D PKG_MESONT=ON -D PKG_MGPT=ON -D PKG_ML-PACE=ON -D PKG_ML-RANN=ON -D PKG_MOLFILE=ON -D PKG_PTM=ON -D PKG_QTB=ON -D PKG_SMTBQ=ON +cmake --build build-release --target all --parallel 16 +cmake --build build-release --target install +/usr/musl/bin/x86_64-linux-musl-strip lammps-static/bin/* +tar -czvvf lammps-linux-x86_64-19Nov2024.tar.gz lammps-static ``` +The resulting tar archive can be uploaded to the GitHub release page with: + +``` +gh release upload patch_19Nov2024 lammps-linux-x86_64-19Nov2024.tar.gz +``` + +Also build serial executable packages that also include LAMMPS-GUI for +Linux, macOS, and Windows, and upload them to the GitHub release. + +TODO: +- update container image to a more recent Fedora version and include libcurl-devel openssl-devel flatpak +- add detailed commands for building GUI packages on Ubuntu 20.04LTS (move to 22.04LTS?), macOS, Windows cross-compiler, flatpak and upload to GitHub +- build all Windows cross-compiled installer packages using lammps-packages repo + +### Update download website + +Check out the LAMMPS website repo +https://github.com/lammps/lammps-website.git and edit the file +`src/download.txt` for the new release. Test translation with `make +html` and review `html/download.html` Then add and commit to git and +push the changes to GitHub. The Temple Jenkis cluster will +automatically update https://www.lammps.org/download.html accordingly. + +Notify Steve of the release so he can update `src/bug.txt` on the +website from the available release notes. ## LAMMPS Stable Release -A LAMMPS stable release is prepared about once per year in the months July, August, or September. -One (or two, if needed) feature releases before the stable release shall contain only bug fixes -or minor feature updates in optional packages. Also substantial changes to the core of the code -shall be applied rather toward the beginning of a development cycle between two stable releases -than toward the end. The intention is to stablilize significant change to the core and have -outside users and developers try them out during the development cycle; the sooner the changes -are included, the better chances for spotting peripheral bugs and issues. +A LAMMPS stable release is prepared about once per year in the months +July, August, or September. One (or two, if needed) feature releases +before the stable release shall contain only bug fixes or minor feature +updates in optional packages. Also substantial changes to the core of +the code shall be applied rather toward the beginning of a development +cycle between two stable releases than toward the end. The intention is +to stablilize significant change to the core and have outside users and +developers try them out during the development cycle; the sooner the +changes are included, the better chances for spotting peripheral bugs +and issues. ### Prerequesites -Before making a stable release all remaining backported bugfixes shall be released as a (final) -stable update release (see below). +Before making a stable release all remaining backported bugfixes shall +be released as a (final) stable update release (see below). -A LAMMPS stable release process starts like a feature release (see above), only that this feature -release is called a "Stable Release Candidate" and no assets are uploaded to GitHub. +A LAMMPS stable release process starts like a feature release (see +above), only that this feature release is called a "Stable Release +Candidate" and no assets are uploaded to GitHub. ### Synchronize 'maintenance' branch with 'release' -The state of the 'release' branch is then transferred to the 'maintenance' branch (which will -have diverged significantly from 'release' due to the selectively backported bug fixes). +The state of the 'release' branch is then transferred to the +'maintenance' branch (which will have diverged significantly from +'release' due to the selectively backported bug fixes). ### Fast-forward merge of 'maintenance' into 'stable' and apply tag -At this point it should be possible to do a fast-forward merge of 'maintenance' to 'stable' -and then apply the stable\_DMmmYYYY tag. +At this point it should be possible to do a fast-forward merge of +'maintenance' to 'stable' and then apply the stable\_DMmmYYYY tag. ### Push branches and tags