Merge pull request #4451 from akohlmey/next_release

Step version strings for next feature release

.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
+The following notes chronicle the current steps for preparing and
-definitions of LAMMPS versions and releases mean, please refer to [the corresponding section in the
+publishing LAMMPS releases.  For definitions of LAMMPS versions and
-LAMMPS manual](https://docs.lammps.org/Manual_version.html).
+releases, 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'
+A LAMMPS feature release is currently prepared after about 500 to 750
-branch or after a period of four weeks up to two months.  This is not a fixed rule, though, since
+commits to the 'develop' branch or after a period of four weeks up to
-external circumstances can cause delays in preparing a release, or pull requests that are desired to
+two months.  This is not a fixed rule, though, since external
-be merged for the release are not yet completed.
+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
+- set the LAMMPS\_VERSION define to the planned release date in
-  "D Mmm YYYY" or "DD Mmm YYYY"
+  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
+- update all TBD arguments for ..versionadded::, ..versionchanged::
-  planned release date in the format "DMmmYYYY" or "DDMmmYYYY"
+  ..deprecated:: to the planned release date in the format "DMmmYYYY" or
-- check release notes for merged new features and check if ..versionadded:: or ..versionchanged::
+  "DDMmmYYYY"
-  are missing and need to be added
+- check release notes for merged new features and check if
-Submit this pull request, rebase if needed.  This is the last pull request merged for the release
+  ..versionadded:: or ..versionchanged:: are missing and need to be
-and should not contain any other changes. (Exceptions: this document, last minute trivial(!) changes).
+  added
 
-This PR shall not be merged before **all** pending tests have completed and cleared. If needed, a
+Submit this pull request, rebase if needed.  This is the last pull
-bugfix pull request should be created and merged to clear all tests.
+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
+When all pending pull requests for the release are merged and have
-'next\_release' branch is merged into 'develop'.
+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
+Check out or update the 'develop' branch locally, pull the latest
-release tag (for historical reasons the tag starts with "patch_" followed by the date, and finally
+changes, merge them into 'release' with a fast forward(!) merge, and
-push everything back to GitHub. Example:
+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,137 @@ 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
+Applying this tag will trigger two actions on the Temple Jenkins cluster:
-existing draft for any necessary changes from pull requests that were merged but are not listed.
+- The online manual at https://docs.lammps.org/ will be updated to the
-Then select the applied tag for the release in the "Choose a tag" dropdown list. Go to the bottom of
+  state of the 'release' branch.  Merges to the 'develop' branch will
-the list and select the "Set as pre-release" checkbox.  The "Set as the latest release" button is
+  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
+If everything is in order, you can click on the "Publish release"
-draft" and finish pending tasks until you can return to edit the release page and publish it.
+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
+Build a fully static LAMMPS installation using a musl-libc
-the https://docs.lammps.org/ website with the documentation for the new feature release
+cross-compiler, install into a lammps-static folder, and create a
-and it will create a tarball for download (which contains the translated manual).
+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
+``` sh
-lammps-static folder, and create a tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a
+rm -rf release-packages
-corresponding date with a future release) from the lammps-static folder and upload it to GitHub
+mkdir release-packages
+cd release-packages
+wget https://download.lammps.org/static/fedora41_musl.sif
+apptainer shell fedora41_musl.sif
+git clone -b release --depth 10 https://github.com/lammps/lammps.git lammps-release
+cmake -S lammps-release/cmake -B build-release -G Ninja -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
+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
+exit # fedora 41 container
+```
+
+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
+```
+
+Make sure you have the `flatpak` and `flatpak-builder` packages
+installed locally (they cannot be used from the container) and build a
+LAMMPS and LAMMPS-GUI flatpak bundle in the `release-packages` folder
 with:
 
-```
+``` sh
-gh release upload patch_19Nov2024 ~/Downloads/lammps-linux-x86_64-19Nov2024.tar.gz
+flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+flatpak-builder  --force-clean --verbose --repo=$PWD/flatpak-repo --install-deps-from=flathub --state-dir=$PWD --user --ccache --default-branch=release flatpak-build lammps-release/tools/lammps-gui/org.lammps.lammps-gui.yml
+flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak org.lammps.lammps-gui release
 ```
 
+The resulting flatpak bundle file can be uploaded to the GitHub release page with:
+
+```
+gh release upload patch_19Nov2024 LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak
+```
+
+Also build serial executable packages that also include LAMMPS-GUI for
+Linux, macOS, and Windows, and upload them to the GitHub release.
+
+Clean up:
+
+``` sh
+cd ..
+rm -r release-packages
+```
+
+TODO:
+- add detailed commands for building GUI packages on Ubuntu 20.04LTS (move to 22.04LTS?),
+  macOS, and Windows cross-compiler 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.
+A LAMMPS stable release is prepared about once per year in the months
-One (or two, if needed) feature releases before the stable release shall contain only bug fixes
+July, August, or September.  One (or two, if needed) feature releases
-or minor feature updates in optional packages.  Also substantial changes to the core of the code
+before the stable release shall contain only bug fixes or minor feature
-shall be applied rather toward the beginning of a development cycle between two stable releases
+updates in optional packages.  Also substantial changes to the core of
-than toward the end.  The intention is to stablilize significant change to the core and have
+the code shall be applied rather toward the beginning of a development
-outside users and developers try them out during the development cycle; the sooner the changes
+cycle between two stable releases than toward the end.  The intention is
-are included, the better chances for spotting peripheral bugs and issues.
+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)
+Before making a stable release all remaining backported bugfixes shall
-stable update release (see below).
+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
+A LAMMPS stable release process starts like a feature release (see
-release is called a "Stable Release Candidate" and no assets are uploaded to GitHub.
+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
+The state of the 'release' branch is then transferred to the
-have diverged significantly from 'release' due to the selectively backported bug fixes).
+'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'
+At this point it should be possible to do a fast-forward merge of
-and then apply the stable\_DMmmYYYY tag.
+'maintenance' to 'stable' and then apply the stable\_DMmmYYYY tag.
 
 ### Push branches and tags
 

doc/lammps.1

@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "19 November 2024" "2024-11-19"
+.TH LAMMPS "1" "4 February 2025" "2025-02-04"
 .SH NAME
 .B LAMMPS
-\- Molecular Dynamics Simulator.  Version 19 November 2024
+\- Molecular Dynamics Simulator.  Version 4 February 2025
 
 .SH SYNOPSIS
 .B lmp
@@ -311,7 +311,7 @@ the chapter on errors in the
 manual gives some additional information about error messages, if possible.
 
 .SH COPYRIGHT
-© 2003--2024 Sandia Corporation
+© 2003--2025 Sandia Corporation
 
 This package is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as

doc/src/Fortran.rst

@@ -1470,7 +1470,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    LAMMPS equal style variable string, evaluates it and returns the resulting
    scalar value as a floating-point number.
 
-   .. versionadded:: TBD
+   .. versionadded:: 4Feb2025
 
    :p character(len=\*) expr: string to be evaluated
    :to: :cpp:func:`lammps_eval`
@@ -1482,7 +1482,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
 
    Clear whether a compute has been invoked
 
-   .. versionadded:: TBD
+   .. versionadded:: 4Feb2025
 
    :to: :cpp:func:`lammps_clearstep_compute`
 
@@ -1493,7 +1493,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    Add timestep to list of future compute invocations
    if the compute has been invoked on the current timestep
 
-   .. versionadded:: TBD
+   .. versionadded:: 4Feb2025
 
    overloaded for 32-bit and 64-bit integer arguments
 
@@ -1506,7 +1506,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
 
    Add timestep to list of future compute invocations
 
-   .. versionadded:: TBD
+   .. versionadded:: 4Feb2025
 
    overloaded for 32-bit and 64-bit integer arguments
 

doc/src/angle_mwlc.rst

@@ -21,7 +21,7 @@ Examples
 Description
 """""""""""
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 The *mwlc* angle style models a meltable wormlike chain and can be used
 to model non-linear bending elasticity of polymers, e.g. DNA.  *mwlc*

doc/src/bond_bpm_spring.rst

@@ -123,7 +123,7 @@ heuristic maximum strain used by typical non-bpm bond styles. Similar behavior
 to *break no* can also be attained by setting an arbitrarily high value of
 :math:`\epsilon_c`. One cannot use *break no* with *smooth yes*.
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 The *volume/factor* keyword toggles whether an additional multibody
 contribution is added to he force using the formulation in

doc/src/compute_gaussian_grid_local.rst

@@ -30,7 +30,7 @@ Examples
 Description
 """""""""""
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 Define a computation that calculates a Gaussian representation of the ionic
 structure. This representation is used for the efficient evaluation

doc/src/fix_efield_lepton.rst

@@ -40,7 +40,7 @@ Examples
 Description
 """""""""""
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 Add an electric potential :math:`V` that applies to a group of charged atoms a force :math:`\vec{F} = q \vec{E}`,
 and to dipoles a force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}` and torque :math:`\vec{T} = \vec{p} \times \vec{E}`,

doc/src/fix_imd.rst

@@ -120,7 +120,7 @@ with different units or as a measure to tweak the forces generated by
 the manipulation of the IMD client, this option allows to make
 adjustments.
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 In `IMDv3 <IMDv3_>`_, the IMD protocol has been extended to allow for
 the transmission of simulation time, box dimensions, atomic coordinates,

doc/src/pair_bpm_spring.rst

@@ -85,7 +85,7 @@ commands, or by mixing as described below:
 * :math:`r_c`           (distance units)
 * :math:`\gamma`        (force/velocity units)
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 Additionally, if *anharmonic* is set to *yes*, a fourth coefficient
 must be provided:

doc/src/pair_dispersion_d3.rst

@@ -26,7 +26,7 @@ Examples
 Description
 """""""""""
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 Style *dispersion/d3* computes the dispersion energy-correction used in
 the DFT-D3 method of Grimme :ref:`(Grimme1) <Grimme1>`.  It would

doc/src/pair_hbond_dreiding.rst

@@ -111,7 +111,7 @@ potential for the Donor-Acceptor interactions. :ref:`(Liu) <Liu>` showed
 that the Morse form gives improved results for Dendrimer simulations,
 when n = 2.
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 The style variants *hbond/dreiding/lj/angleoffset* and
 *hbond/dreiding/lj/angleoffset* take the equilibrium angle of the AHD as

python/lammps/core.py

@@ -1700,7 +1700,7 @@ class lammps(object):
   def eval(self, expr):
     """ Evaluate a LAMMPS immediate variable expression
 
-    .. versionadded:: TBD
+    .. versionadded:: 4Feb2025
 
     This function is a wrapper around the function :cpp:func:`lammps_eval`
     of the C library interface.  It evaluates and expression like in

src/library.cpp

@@ -2931,7 +2931,7 @@ int lammps_variable_info(void *handle, int idx, char *buffer, int buf_size) {
  *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 This function takes a string with an expression that can be used
 for :doc:`equal style variables <variable>`, evaluates it and returns
@@ -2966,7 +2966,7 @@ double lammps_eval(void *handle, const char *expr)
  *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
    This function clears the invoked flag of all computes.
    Called everywhere that computes are used, before computes are invoked.
@@ -2992,7 +2992,7 @@ void lammps_clearstep_compute(void *handle) {
  *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
    loop over all computes
    schedule next invocation for those that store invocation times
@@ -3019,7 +3019,7 @@ void lammps_addstep_compute_all(void *handle, void *newstep) {
  *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
    loop over computes that store invocation times
    if its invoked flag set on this timestep, schedule next invocation

src/utils.h

@@ -45,7 +45,7 @@ namespace utils {
    *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 This function compares two strings while skipping over any kind of whitespace
 (blank, tab, newline, carriage return, etc.).
@@ -62,7 +62,7 @@ This function compares two strings while skipping over any kind of whitespace
    *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 This function compresses whitespace in a string to just a single blank.
 
@@ -96,7 +96,7 @@ This function compresses whitespace in a string to just a single blank.
    *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 This function is a helper function for error messages.  It creates extra output
 in error messages.  It will produce either two or three lines: the original last
@@ -147,7 +147,7 @@ output are compressed to a single blank by calling :cpp:func:`strcompress()`
    *
 \verbatim embed:rst
 
-.. versionadded:: TBD
+.. versionadded:: 4Feb2025
 
 \endverbatim
    *

src/version.h

@@ -1,2 +1 @@
-#define LAMMPS_VERSION "19 Nov 2024"
+#define LAMMPS_VERSION "4 Feb 2025"
-#define LAMMPS_UPDATE "Development"