ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update manual for revised release and branch names

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-02-10 00:50:36 -05:00
parent c37c752d36
commit 58a90d613b
7 changed files with 93 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Build_manual.rst
View File

@ -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/ <https://docs.lammps.org/>`_.
A version of the manual corresponding to the ongoing development (that is

31
doc/src/Howto_github.rst
View File

@ -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_<Day><Month><Year>" 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_<Day><Month><Year>" to simplify comparisons between releases.
For stable releases additional "stable_<Day><Month><Year>" tags are
applied and update releases are tagged with
"stable_<Day><Month><Year>_update<Number>", 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
<https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

32
doc/src/Install_git.rst
View File

@ -26,15 +26,18 @@ provides `limited support for subversion clients <svn_>`_.
.. _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 <branch name>".)
*--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::

30
doc/src/Install_linux.rst
View File

@ -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 <static>`
- :ref:`Pre-built Ubuntu and Debian Linux executables <ubuntu>`
- :ref:`Pre-built Fedora Linux executables <fedora>`
- :ref:`Pre-built EPEL Linux executables (RHEL, CentOS) <epel>`
@ -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/ <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-<version>.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
<https://aur.archlinux.org/packages/lammps>`_, `lammps-beta
<https://aur.archlinux.org/packages/lammps>`_ and `lammps-git
<https://aur.archlinux.org/packages/lammps>`_. 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.

17
doc/src/Install_tarball.rst
View File

@ -10,15 +10,15 @@ of the `LAMMPS website <lws_>`_.
.. _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 <bug_>`_ 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 <bug_>`_ 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
<older_>`_.
@ -44,7 +44,8 @@ with the following command, to create a lammps-<version> 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

28
doc/src/Manual_version.rst
View File

@ -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 <https://www.lammps.org/bug.html>`_. More detailed release
notes are `available on GitHub
<https://github.com/lammps/lammps/releases/>`_.
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
<https://www.lammps.org/bug.html>`_. More detailed release notes are
`available on GitHub <https://github.com/lammps/lammps/releases/>`_.
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 <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

4
doc/src/Modify_contribute.rst
View File

@ -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
<Howto_github>` page for instructions on how to submit your changes or