diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst index eaa9f44a1c..c726d37ea6 100644 --- a/doc/src/Build_manual.rst +++ b/doc/src/Build_manual.rst @@ -33,7 +33,7 @@ various tools and files. Some of them have to be installed (see below). For the rest the build process will attempt to download and install them into a python virtual environment and local folders. -A current version of the manual (latest patch release, that is the state +A current version of the manual (latest feature release, that is the state of the *release* branch) is is available online at: `https://docs.lammps.org/ `_. A version of the manual corresponding to the ongoing development (that is diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index 0b465d318b..cbe1264d52 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -476,16 +476,25 @@ to your remote(s) as well: **Recent changes in the workflow** -Some changes to the workflow are not captured in this tutorial. For -example, in addition to the *develop* branch, to which all new features -should be submitted, there is also a *release* and a *stable* branch; -these have the same content as *develop*, but are only updated after a -patch release or stable release was made. Furthermore, the naming of -the patches now follow the pattern "patch_" to -simplify comparisons between releases. Finally, all patches and -submissions are subject to automatic testing and code checks to make -sure they at the very least compile. +Some recent changes to the workflow are not captured in this tutorial. +For example, in addition to the *develop* branch, to which all new +features should be submitted, there is also a *release*, a *stable*, and +a *maintenance* branch; the *release* branch is updated from the +*develop* as part of a feature release, and *stable* (together with +*release*) are updated from *develop* when a stable release is made. In +between stable releases, selected bug fixes and infrastructure updates +are back-ported from the *develop* branch to the *maintenance* branch +and occasionally merged to *stable* as an update release. -A discussion of the LAMMPS developer GitHub workflow can be found in the -file `doc/github-development-workflow.md +Furthermore, the naming of the release tags now follow the pattern +"patch_" to simplify comparisons between releases. +For stable releases additional "stable_" tags are +applied and update releases are tagged with +"stable__update", Finally, all releases and +submissions are subject to automatic testing and code checks to make +sure they compile with a variety of compilers and popular operating +systems. Some unit and regression testing is applied as well. + +A detailed discussion of the LAMMPS developer GitHub workflow can be +found in the file `doc/github-development-workflow.md `_ diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index de948b3671..b11477689b 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -26,15 +26,18 @@ provides `limited support for subversion clients `_. .. _git: https://git-scm.com .. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github -You can follow the LAMMPS development on 3 different git branches: +You can follow the LAMMPS development on 4 different git branches: -* **stable** : this branch is updated from the *release* branch with - every stable release version and also has selected bug fixes and updates - back-ported from the *develop* branch * **release** : this branch is updated with every patch or feature release; updates are always "fast-forward" merges from *develop* * **develop** : this branch follows the ongoing development and is updated with every merge commit of a pull request +* **stable** : this branch is updated from the *release* branch with + every stable release version and also has selected bug fixes with every + update release when the *maintenance* branch is merged into it +* **maintenance** : this branch collects back-ported bug fixes from the + *develop* branch to the *stable* branch. It is used to update *stable* + for update releases and it synchronized with *stable* at each stable release. To access the git repositories on your box, use the clone command to create a local copy of the LAMMPS repository with a command like: @@ -60,17 +63,17 @@ between them at any time using "git checkout ".) *--depth* git command line flag. That will create a "shallow clone" of the repository, which contains only a subset of the git history. Using a depth of 1000 is usually sufficient to include the head - commits of the *develop* and the *release* branches. To include the - head commit of the *stable* branch you may need a depth of up - to 10000. If you later need more of the git history, you can always - convert the shallow clone into a "full clone". + commits of the *develop*, the *release*, and the *maintenance* + branches. To include the head commit of the *stable* branch you may + need a depth of up to 10000. If you later need more of the git + history, you can always convert the shallow clone into a "full + clone". Once the command completes, your directory will contain the same files as if you unpacked a current LAMMPS tarball, with the exception, that -the HTML documentation files are not included. They can be fetched -from the LAMMPS website by typing ``make fetch`` in the doc directory. -Or they can be generated from the content provided in ``doc/src`` by -typing ``make html`` from the ``doc`` directory. +the HTML documentation files are not included. They can be generated +from the content provided in ``doc/src`` by typing ``make html`` from +the ``doc`` directory. After initial cloning, as bug fixes and new features are added to LAMMPS you can stay up-to-date by typing the following git commands @@ -79,8 +82,9 @@ from within the "mylammps" directory: .. code-block:: bash git checkout release # not needed if you always stay in this branch - git checkout stable # use one of these 3 checkout commands + git checkout stable # use one of these 4 checkout commands git checkout develop # to choose the branch to follow + git checkout maintenance git pull Doing a "pull" will not change any files you have added to the LAMMPS @@ -145,7 +149,7 @@ changed. How to do this depends on the build system you are using. to enforce consistency of the source between the src folder and package directories. This is OK to do even if you don't use any packages. The ``make purge`` command removes any deprecated - src files if they were removed by the patch from a package + src files if they were removed by the update from a package subdirectory. .. warning:: diff --git a/doc/src/Install_linux.rst b/doc/src/Install_linux.rst index bf33e35ee2..f902b1b987 100644 --- a/doc/src/Install_linux.rst +++ b/doc/src/Install_linux.rst @@ -3,6 +3,7 @@ Download an executable for Linux Binaries are available for different versions of Linux: +- :ref:`Pre-built static Linux x86_64 executables ` - :ref:`Pre-built Ubuntu and Debian Linux executables ` - :ref:`Pre-built Fedora Linux executables ` - :ref:`Pre-built EPEL Linux executables (RHEL, CentOS) ` @@ -21,6 +22,33 @@ Binaries are available for different versions of Linux: ---------- +.. _static: + +Pre-built static Linux x86_64 executables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pre-built LAMMPS executables for Linux, that are statically linked and +compiled for 64-bit x86 CPUs (x86_64 or AMD64) are available for download +at `https://download.lammps.org/static/ `_. +Because of that static linkage (and unlike the Linux distribution specific +packages listed below), they do not depend on any installed software and +thus should run on *any* 64-bit x86 machine with *any* Linux version. + +These executable include most of the available packages and multi-thread +parallelization (via INTEL, KOKKOS, or OPENMP package). They are **not** +compatible with MPI. Several of the LAMMPS tools executables (e.g. ``msi2lmp``) +and the ``lammps-shell`` program are included as well. Because of the +static linkage, there is no ``liblammps.so`` library file and thus also the +LAMMPS python module, which depends on it, is not included. + +The compressed tar archives available for download have names following +the pattern `lammps-linux-x86_64-.tar.gz` and will all unpack +into a ``lammps-static`` folder. The executables are then in the +``lammps-static/bin/`` folder. Since they do not depend on any other +software, they may be freely moved or copied around. + +---------- + .. _ubuntu: Pre-built Ubuntu and Debian Linux executables @@ -232,7 +260,7 @@ There are three scripts available, named `lammps `_, `lammps-beta `_ and `lammps-git `_. They respectively -package the stable, patch and git releases. +package the stable, feature, and git releases. To install, you will need to have the git package installed. You may use any of the above names in-place of lammps. diff --git a/doc/src/Install_tarball.rst b/doc/src/Install_tarball.rst index 0765d71044..64d73ee356 100644 --- a/doc/src/Install_tarball.rst +++ b/doc/src/Install_tarball.rst @@ -10,15 +10,15 @@ of the `LAMMPS website `_. .. _lws: https://www.lammps.org You have two choices of tarballs, either the most recent stable release -or the most current patch or feature release. Stable releases occur a -few times per year, and undergo more testing before release. Feature -releases occur every 4 to 8 weeks. The new contents in all feature -releases are listed on the `bug and feature page `_ of the LAMMPS -homepage. +or the most recent feature release. Stable releases occur a few times +per year, and undergo more testing before release. Also, between stable +releases bug fixes from the feature releases are back-ported and the +tarball occasionally updated. Feature releases occur every 4 to 8 +weeks. The new contents in all feature releases are listed on the `bug +and feature page `_ of the LAMMPS homepage. Both tarballs include LAMMPS documentation (HTML and PDF files) -corresponding to that version. The download page also has an option -to download the current-version LAMMPS documentation by itself. +corresponding to that version. Tarballs of older LAMMPS versions can also be downloaded from `this page `_. @@ -44,7 +44,8 @@ with the following command, to create a lammps- directory: unzip lammps*.zip -This version corresponds to the selected LAMMPS patch or stable release. +This version corresponds to the selected LAMMPS feature or stable +release. .. _git: https://github.com/lammps/lammps/releases diff --git a/doc/src/Manual_version.rst b/doc/src/Manual_version.rst index 6f99b9f117..8fb28fef84 100644 --- a/doc/src/Manual_version.rst +++ b/doc/src/Manual_version.rst @@ -12,13 +12,12 @@ into pull requests. Pull requests will be merged into the *develop* branch of the git repository after they pass automated testing and code review by the LAMMPS developers. When a sufficient number of changes have accumulated *and* the *develop* branch version passes an extended -set of automated tests, we release it as a *feature release* (or patch -release), which are currently made every 4 to 8 weeks. The *release* -branch of the git repository is updated with every such release. A -summary of the most important changes of the patch releases are on `this -website page `_. More detailed release -notes are `available on GitHub -`_. +set of automated tests, we release it as a *feature release*, which are +currently made every 4 to 8 weeks. The *release* branch of the git +repository is updated with every such release. A summary of the most +important changes of the patch releases are on `this website page +`_. More detailed release notes are +`available on GitHub `_. Once or twice a year, we have a "stabilization period" where we apply only bug fixes and small, non-intrusive changes to the *develop* @@ -28,13 +27,14 @@ several variants of static code analysis are run to improve the overall code quality, consistency, and compliance with programming standards, best practices and style conventions. -The latest patch release after such a period is then also labeled as a -*stable* version and the *stable* branch is updated with it. Between -stable releases, we occasionally release updates to the stable release -containing only bug fixes and updates back-ported from the *develop* -branch and update the *stable* branch accordingly. +The release after such a stabilization period is called a *stable* +version and both, the *release* and the *stable* branches are updated +with it. Between stable releases, we collect back-ported bug fixes and +updates from the *develop* branch in the *maintenance* branch. From the +*maintenance* branch we make occasional update releases and update the +*stable* branch accordingly. -Each version of LAMMPS contains all the documented features up to and +Each version of LAMMPS contains all the documented *features* up to and including its version date. For recently added features, we add markers to the documentation at which specific LAMMPS version a feature or keyword was added or significantly changed. @@ -45,7 +45,7 @@ directory name created when you unpack a tarball. And it is on the first page of the :doc:`manual `. * If you browse the HTML pages of the online version of the LAMMPS - manual, they will by default describe the most current patch release + manual, they will by default describe the most current feature release version of LAMMPS. In the navigation bar on the bottom left, there is the option to view instead the documentation for the most recent *stable* version or the documentation corresponding to the state of diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 5ccb83e328..d36e68b093 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -80,8 +80,8 @@ integrated via pull requests on GitHub and cannot be merged without passing the automated testing and an approving review by a LAMMPS core developer. Thus before submitting your contribution, you should first make certain, that your added or modified code compiles and works -correctly with the latest patch-level or development version of LAMMPS -and contains all bug fixes from it. +correctly with the latest development version of LAMMPS and contains all +bug fixes from it. Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial ` page for instructions on how to submit your changes or