From 3237c30117938f4a49bf7abac1ea0b0c1f54ae28 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 18 Dec 2023 15:40:14 -0500 Subject: [PATCH] reorganize the LAMMPS version and development description --- doc/github-development-workflow.md | 8 +-- doc/src/Howto_github.rst | 10 ++-- doc/src/Install_git.rst | 20 +++---- doc/src/Manual_version.rst | 91 +++++++++++++++++++----------- 4 files changed, 77 insertions(+), 52 deletions(-) diff --git a/doc/github-development-workflow.md b/doc/github-development-workflow.md index fccd75d29a..e16ae82764 100644 --- a/doc/github-development-workflow.md +++ b/doc/github-development-workflow.md @@ -36,10 +36,10 @@ requests. MUST be submitted as a pull request to GitHub. All changes to the "develop" branch must be made exclusively through merging pull requests. The "release" and "stable" branches, respectively, are only to be -updated upon feature or stable releases based on the associated -tags. Updates to the stable release in between stable releases +updated upon "feature releases" or "stable releases" based on the +associated tags. Updates to the stable release in between stable releases (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 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 extensive and time-consuming tests (including regression testing) are 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 and all post-merge testing has been successful. These feature releases are marked with a `patch_` tag and the "release" branch diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst index cbe1264d52..b81716c09d 100644 --- a/doc/src/Howto_github.rst +++ b/doc/src/Howto_github.rst @@ -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 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. +*develop* branch 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. Furthermore, the naming of the release tags now follow the pattern "patch_" to simplify comparisons between releases. diff --git a/doc/src/Install_git.rst b/doc/src/Install_git.rst index b6d3ced0a5..45e364a226 100644 --- a/doc/src/Install_git.rst +++ b/doc/src/Install_git.rst @@ -28,16 +28,16 @@ provides `limited support for subversion clients `_. You can follow the LAMMPS development on 4 different git branches: -* **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. +* **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* +* **maintenance** : this branch collects back-ported bug fixes from the + *develop* branch to the *stable* branch. It is used to update the + *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 create a local copy of the LAMMPS repository with a command like: diff --git a/doc/src/Manual_version.rst b/doc/src/Manual_version.rst index 8fb28fef84..f123267acf 100644 --- a/doc/src/Manual_version.rst +++ b/doc/src/Manual_version.rst @@ -3,45 +3,25 @@ What does a LAMMPS version mean 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 -correctly and reliably at all times. You can follow its development -in a public `git repository on GitHub `_. - -Modifications of the LAMMPS source code (like bug fixes, code refactors, -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. 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 -`_. 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* -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. +correctly and reliably at all times. Also, several variants of static +code analysis are run regularly to maintain or improve the overall code +quality, consistency, and compliance with programming standards, best +practices and style conventions. You can follow its development in a +public `git repository on GitHub `_. 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. -The version date is printed to the screen and log file every time you run -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 +Identifying the Version +^^^^^^^^^^^^^^^^^^^^^^^ + +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 `. * If you browse the HTML pages of the online version of the LAMMPS @@ -53,3 +33,48 @@ first page of the :doc:`manual `. * If you browse the HTML pages included in your downloaded tarball, they describe the version you have, which may be older than the online 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 `_. More detailed release +notes are `available on GitHub +`_. + +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.