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

reorganize the LAMMPS version and development description

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-12-18 15:40:14 -05:00
parent 94b62fa98b
commit 3237c30117
4 changed files with 77 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/github-development-workflow.md
View File

@ -36,10 +36,10 @@ requests.
MUST be submitted as a pull request to GitHub. All changes to the MUST be submitted as a pull request to GitHub. All changes to the
"develop" branch must be made exclusively through merging pull requests. "develop" branch must be made exclusively through merging pull requests.
The "release" and "stable" branches, respectively, are only to be The "release" and "stable" branches, respectively, are only to be
updated upon feature or stable releases based on the associated updated upon "feature releases" or "stable releases" based on the
tags. Updates to the stable release in between stable releases associated tags. Updates to the stable release in between stable releases
(for example, back-ported bug fixes) are first merged into the "maintenance" (for example, back-ported bug fixes) are first merged into the "maintenance"
branch and then into the "stable" branch as update releases. branch and then into the "stable" branch as "stable update releases".
Pull requests may also be submitted to (long-running) feature branches Pull requests may also be submitted to (long-running) feature branches
created by LAMMPS developers inside the LAMMPS project, if needed. Those created by LAMMPS developers inside the LAMMPS project, if needed. Those
@ -131,7 +131,7 @@ testing -- that the code in the branch "develop" does not get easily
broken. These tests are run after every update to a pull request. More broken. These tests are run after every update to a pull request. More
extensive and time-consuming tests (including regression testing) are extensive and time-consuming tests (including regression testing) are
performed after code is merged to the "develop" branch. There are feature performed after code is merged to the "develop" branch. There are feature
releases of LAMMPS made about every 4-6 weeks at a point, when the LAMMPS releases of LAMMPS made about every 4-8 weeks at a point, when the LAMMPS
developers feel, that a sufficient number of changes have been included developers feel, that a sufficient number of changes have been included
and all post-merge testing has been successful. These feature releases are and all post-merge testing has been successful. These feature releases are
marked with a `patch_<version date>` tag and the "release" branch marked with a `patch_<version date>` tag and the "release" branch

10
doc/src/Howto_github.rst
View File

@ -480,11 +480,11 @@ Some recent changes to the workflow are not captured in this tutorial.
For example, in addition to the *develop* branch, to which all new For example, in addition to the *develop* branch, to which all new
features should be submitted, there is also a *release*, a *stable*, and features should be submitted, there is also a *release*, a *stable*, and
a *maintenance* branch; the *release* branch is updated from the a *maintenance* branch; the *release* branch is updated from the
*develop* as part of a feature release, and *stable* (together with *develop* branch as part of a "feature release", and *stable* (together
*release*) are updated from *develop* when a stable release is made. In with *release*) are updated from *develop* when a "stable release" is
between stable releases, selected bug fixes and infrastructure updates made. In between stable releases, selected bug fixes and infrastructure
are back-ported from the *develop* branch to the *maintenance* branch updates are back-ported from the *develop* branch to the *maintenance*
and occasionally merged to *stable* as an update release. branch and occasionally merged to *stable* as an update release.
Furthermore, the naming of the release tags now follow the pattern Furthermore, the naming of the release tags now follow the pattern
"patch_<Day><Month><Year>" to simplify comparisons between releases. "patch_<Day><Month><Year>" to simplify comparisons between releases.

16
doc/src/Install_git.rst
View File

@ -28,16 +28,16 @@ provides `limited support for subversion clients <svn_>`_.
You can follow the LAMMPS development on 4 different git branches: You can follow the LAMMPS development on 4 different git branches:
* **release** : this branch is updated with every patch or feature release; * **develop** : this branch follows the ongoing development and is
updated with every merge commit of a pull request
* **release** : this branch is updated with every "feature release";
updates are always "fast-forward" merges from *develop* 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 * **maintenance** : this branch collects back-ported bug fixes from the
*develop* branch to the *stable* branch. It is used to update *stable* *develop* branch to the *stable* branch. It is used to update the
for update releases and it synchronized with *stable* at each stable release. *stable* branch for "stable update releases".
* **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
To access the git repositories on your box, use the clone command to 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: create a local copy of the LAMMPS repository with a command like:

91
doc/src/Manual_version.rst
View File

@ -3,45 +3,25 @@ What does a LAMMPS version mean
The LAMMPS "version" is the date when it was released, such as 1 May The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously, and we aim to keep it working 2014. LAMMPS is updated continuously, and we aim to keep it working
correctly and reliably at all times. You can follow its development correctly and reliably at all times. Also, several variants of static
in a public `git repository on GitHub <https://github.com/lammps/lammps>`_. code analysis are run regularly to maintain or improve the overall code
quality, consistency, and compliance with programming standards, best
Modifications of the LAMMPS source code (like bug fixes, code refactors, practices and style conventions. You can follow its development in a
updates to existing features, or addition of new features) are organized public `git repository on GitHub <https://github.com/lammps/lammps>`_.
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*, 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*
branch. At the same time, the code is subjected to more detailed and
thorough manual testing than the default automated testing. Also,
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 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 including its version date. For recently added features, we add markers
to the documentation at which specific LAMMPS version a feature or to the documentation at which specific LAMMPS version a feature or
keyword was added or significantly changed. keyword was added or significantly changed.
The version date is printed to the screen and log file every time you run Identifying the Version
LAMMPS. It is also in the file src/version.h and in the LAMMPS ^^^^^^^^^^^^^^^^^^^^^^^
directory name created when you unpack a tarball. And it is on the
The version date is printed to the screen and log file every time you
run LAMMPS. There also is an indication, if a LAMMPS binary was
compiled from version with modifications **after** a release.
It is also visible in the file src/version.h and in the LAMMPS directory
name created when you unpack a downloaded tarball. And it is on the
first page of the :doc:`manual <Manual>`. first page of the :doc:`manual <Manual>`.
* If you browse the HTML pages of the online version of the LAMMPS * If you browse the HTML pages of the online version of the LAMMPS
@ -53,3 +33,48 @@ first page of the :doc:`manual <Manual>`.
* If you browse the HTML pages included in your downloaded tarball, they * If you browse the HTML pages included in your downloaded tarball, they
describe the version you have, which may be older than the online describe the version you have, which may be older than the online
version. version.
Development
^^^^^^^^^^^
Modifications of the LAMMPS source code (like bug fixes, code
refactoring, updates to existing features, or addition of new features)
are organized 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.
Feature Releases
^^^^^^^^^^^^^^^^
When a sufficient number of new features and updates have accumulated
*and* the LAMMPS version on the *develop* branch passes an extended 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 *feature release* and a tag in the
format ``patch_1May2014`` is added. A summary of the most important
changes of these releases for the current year are posted on `this
website page <https://www.lammps.org/bug.html>`_. More detailed release
notes are `available on GitHub
<https://github.com/lammps/lammps/releases/>`_.
Stable Releases
^^^^^^^^^^^^^^^
About once a year, we release a *stable release* version of LAMMPS.
This is done after a "stabilization period" where we apply only bug
fixes and small, non-intrusive changes to the *develop* branch but no
new features. At the same time, the code is subjected to more detailed
and thorough manual testing than the default automated testing.
After such a *stable release*, both the *release* and the *stable*
branches are updated and two tags are applied, a ``patch_1May2014`` format
and a ``stable_1May2014`` format tag.
Stable Release Updates
^^^^^^^^^^^^^^^^^^^^^^
Between *stable releases*, we collect bug fixes and updates back-ported
from the *develop* branch in a branch called *maintenance*. From the
*maintenance* branch we make occasional *stable update releases* and
update the *stable* branch accordingly. The first update to the
``stable_1May2014`` release would be tagged as
``stable_1May2014_update1``. These updates contain no new features.