update markdown files for revised branch structure and development wo…

…rkflow

SECURITY.md

@@ -32,17 +32,21 @@ for unicode characters and only all-ASCII source code is accepted.
 
 LAMMPS follows a continuous release development model.  We aim to keep
 the development version (`develop` branch) always fully functional and
-employ a variety of automatic testing procedures to detect failures
-of existing functionality from adding or modifying features.  Most of
-those tests are run on pull requests *before* merging to the `develop`
-branch.  The `develop` branch is protected, so all changes *must* be
-submitted as a pull request and thus cannot avoid the automated tests.
+employ a variety of automatic testing procedures to detect failures of
+existing functionality from adding or modifying features.  Most of those
+tests are run on pull requests and must be passed *before* merging to
+the `develop` branch.  The `develop` branch is protected, so all changes
+*must* be submitted as a pull request and thus cannot avoid the
+automated tests.
 
 Additional tests are run *after* merging.  Before releases are made
 *all* tests must have cleared.  Then a release tag is applied and the
-`release` branch is fast-forwarded to that tag.  This is often referred
-to as a patch release. Bug fixes and updates are
-applied first to the `develop` branch.  Later, they appear in the `release`
-branch when the next patch release occurs.
-For stable releases, selected bug fixes, updates, and new functionality
-are pushed to the `stable` branch and a new stable tag is applied.
+`release` branch is fast-forwarded to that tag.  This is referred to to
+as a "feature release".  Bug fixes and updates are applied first to the
+`develop` branch.  Later, they appear in the `release` branch when the
+next patch release occurs.  For stable releases, backported bug fixes
+and infrastructure updates are first applied to the `maintenance` branch
+and then merged to `stable` and published as "updates".  For a new
+stable release the `stable` branch is updated to the corresponding state
+of the `release` branch and a new stable tag is applied in addition to
+the release tag.

doc/github-development-workflow.md

@@ -27,42 +27,45 @@ should doing the merging itself.  This is currently
 assignment needs to be changed, it shall be done right after a stable
 release.  If the currently assigned developer cannot merge outstanding
 pull requests in a timely manner, or in other extenuating circumstances,
-other core LAMMPS developers with merge rights can merge pull requests,
-when necessary.
+other core LAMMPS developers with merge permissons may merge pull
+requests.
 
 ## Pull Requests
 
-ALL changes to the LAMMPS code and documentation, however trivial, MUST
-be submitted as a pull request to GitHub. All changes to the "develop"
-branch must be made exclusively through merging pull requests. The
+*ALL* changes to the LAMMPS code and documentation, however trivial, 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 patch or stable releases with fast-forward merges based on the
-associated tags. Pull requests may also be submitted to (long-running)
-feature branches created by LAMMPS developers inside the LAMMPS project,
-if needed. Those are not subject to the merge and review restrictions
-discussed in this document, though, but get managed as needed on a
-case-by-case basis.
+upon feature or stable releases based on the associated tags. Updates to
+stable release in between stable releases (e.g. backported bugfixes)
+are first merged into the "maintenance" branch and then into the "stable"
+branch as update releases.
+
+Pull requests may also be submitted to (long-running) feature branches
+created by LAMMPS developers inside the LAMMPS project, if needed. Those
+are not subject to the merge and review restrictions discussed in this
+document, though, but get managed as needed on a case-by-case basis.
 
 ### Pull Request Assignments
 
 Pull requests can be "chaperoned" by one of the LAMMPS core developers.
-This is indicated by who the pull request is assigned to. LAMMPS core
+This is indicated by who the pull request is assigned to.  LAMMPS core
 developers can self-assign or they can decide to assign a pull request
 to a different LAMMPS developer. Being assigned to a pull request means,
 that this pull request may need some work and the assignee is tasked to
 determine whether this might be needed or not, and may either implement
-the required changes or ask the submitter of the pull request to implement
-them.  Even though, all LAMMPS developers may have write access to pull
-requests (if enabled by the submitter, which is the default), only the
-submitter or the assignee of a pull request may do so.  During this
-period the `work_in_progress` label may be applied to the pull
-request.  The assignee gets to decide what happens to the pull request
-next, e.g. whether it should be assigned to a different developer for
-additional checks and changes, or is recommended to be merged.  Removing
-the `work_in_progress` label and assigning the pull request to the
-developer tasked with merging signals that a pull request is ready to be
-merged. In addition, a `ready_for_merge` label may also be assigned
-to signal urgency to merge this pull request quickly.
+the required changes or ask the submitter of the pull request to
+implement them.  Even though, all LAMMPS developers may have write
+access to pull requests (if enabled by the submitter, which is the
+default), only the submitter or the assignee of a pull request may do
+so.  During this period the `work_in_progress` label may be applied to
+the pull request.  The assignee gets to decide what happens to the pull
+request next, e.g. whether it should be assigned to a different
+developer for additional checks and changes, or is recommended to be
+merged.  Removing the `work_in_progress` label and assigning the pull
+request to the developer tasked with merging signals that a pull request
+is ready to be merged. In addition, a `ready_for_merge` label may also
+be assigned to signal urgency to merge this pull request quickly.
 
 ### Pull Request Reviews
 
@@ -126,22 +129,26 @@ changes, i.e. significant effort is made - including automated pre-merge
 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 patch
-releases of LAMMPS every 3-5 weeks at a point, when the LAMMPS
-developers feel, that a sufficient amount of changes have happened, and
-the post-merge testing has been successful. These patch releases 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
+developers feel, that a sufficient amount of changes have been included,
+and all post-merge testing has been successful.  These feature releases are
 marked with a `patch_<version date>` tag and the "release" branch
-follows only these versions (and thus is always supposed to be of
-production quality, unlike "develop", which may be temporary broken, in
-the case of larger change sets or unexpected incompatibilities or side
-effects.
+follows only these versions with fast forward merges.  While "develop" may
+be temporary broken through issues only detected by the post-merge tests,
+The "release" branch is always supposed to be of production quality.
 
-About 1-2 times each year, there are going to be "stable" releases of
+About once each year, there are going to be "stable" releases of
 LAMMPS.  These have seen additional, manual testing and review of
 results from testing with instrumented code and static code analysis.
-Also, the last 1-3 patch releases before a stable release are "release
-candidate" versions which only contain bugfixes and documentation
-updates.  For release planning and the information of code contributors,
-issues and pull requests being actively worked on are assigned a
-"milestone", which corresponds to the next stable release or the stable
-release after that, with a tentative release date.
+Also, the last few feature releases before a stable release are "release
+candidate" versions which only contain bugfixes, feature additions to
+peripheral functionality, and documentation updates.  In between stable
+releases, bugfixes and infrastructure updates are backported from the
+"develop" branch to the "maintenance" branch and occasionally merged
+into "stable" and published as update releases.
+
+For release planning and the information of code contributors, issues
+and pull requests being actively worked on are assigned a "milestone",
+which corresponds to the next stable release or the stable release after
+that, with a tentative release date.