fix grammar and spelling issues
This commit is contained in:
Axel Kohlmeyer
@ -1,12 +1,12 @@
|
||||
# Outline of the GitHub Development Workflow
|
||||
|
||||
This purpose of this document is to provide a point of reference for the
|
||||
The purpose of this document is to provide a point of reference for the
|
||||
core LAMMPS developers and other LAMMPS contributors to understand the
|
||||
choices the LAMMPS developers have agreed on. Git and GitHub provide the
|
||||
tools, but do not set policies, so it is up to the developers to come to
|
||||
an agreement as to how to define and interpret policies. This document
|
||||
is likely to change as our experiences and needs change and we try to
|
||||
adapt accordingly. Last change 2021-09-02.
|
||||
is likely to change as our experiences and needs change, and we try to
|
||||
adapt it accordingly. Last change 2023-02-10.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
@ -22,24 +22,24 @@ adapt accordingly. Last change 2021-09-02.
|
||||
## GitHub Merge Management
|
||||
|
||||
In the interest of consistency, ONLY ONE of the core LAMMPS developers
|
||||
should doing the merging itself. This is currently
|
||||
should do the merging. This is currently
|
||||
[@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer). If this
|
||||
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 permissons may merge pull
|
||||
other core LAMMPS developers with merge permission 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
|
||||
"release" and "stable" branches, respectively are only to be updated
|
||||
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.
|
||||
*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 feature 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.
|
||||
|
||||
Pull requests may also be submitted to (long-running) feature branches
|
||||
created by LAMMPS developers inside the LAMMPS project, if needed. Those
|
||||
@ -49,16 +49,16 @@ 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
|
||||
developers can self-assign or they can decide to assign a pull request
|
||||
This is indicated by whom 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
|
||||
determine whether this might be needed or not. The assignee may either
|
||||
choose to implement 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 should 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
|
||||
@ -73,32 +73,33 @@ People can be assigned to review a pull request in two ways:
|
||||
|
||||
* They can be assigned manually to review a pull request
|
||||
by the submitter or a LAMMPS developer
|
||||
* They can be automatically assigned, because a developers matches
|
||||
a file pattern in the `.github/CODEOWNERS` file, which associates
|
||||
developers with the code they contributed and maintain.
|
||||
* They can be automatically assigned, because a developer's GitHub
|
||||
handle matches a file pattern in the `.github/CODEOWNERS` file,
|
||||
which associates developers with the code they contributed and
|
||||
maintain.
|
||||
|
||||
Reviewers are requested to state their appraisal of the proposed changes
|
||||
and either approve or request changes. People may unassign themselves
|
||||
from review, if they feel not competent about the changes proposed. At
|
||||
least two approvals from LAMMPS developers with write access are required
|
||||
before merging in addition to the automated compilation tests.
|
||||
Merging counts as implicit approval, so does submission of a pull request
|
||||
(by a LAMMPS developer). So the person doing the merge may not also submit
|
||||
an approving review. The feature, that reviews from code owners are "hard"
|
||||
reviews (i.e. they must all be approved before merging is allowed), is
|
||||
currently disabled and it is in the discretion of the merge maintainer to
|
||||
assess when a sufficient degree of approval, especially from external
|
||||
contributors, has been reached in these cases. Reviews may be
|
||||
(automatically) dismissed, when the reviewed code has been changed,
|
||||
and then approval is required a second time.
|
||||
least two approvals from LAMMPS developers with write access are
|
||||
required before merging, in addition to passing all automated
|
||||
compilation and unit tests. Merging counts as implicit approval, so
|
||||
does submission of a pull request (by a LAMMPS developer). So the person
|
||||
doing the merge may not also submit an approving review. The GitHub
|
||||
feature, that reviews from code owners are "hard" reviews (i.e. they
|
||||
must all approve before merging is allowed), is currently disabled.
|
||||
It is in the discretion of the merge maintainer to assess when a
|
||||
sufficient degree of approval has been reached, especially from external
|
||||
collaborators. Reviews may be (automatically) dismissed, when the
|
||||
reviewed code has been changed. Review may be requested a second time.
|
||||
|
||||
### Pull Request Discussions
|
||||
|
||||
All discussions about a pull request should be kept as much as possible
|
||||
on the pull request discussion page on GitHub, so that other developers
|
||||
can later review the entire discussion after the fact and understand the
|
||||
rationale behind choices made. Exceptions to this policy are technical
|
||||
discussions, that are centered on tools or policies themselves
|
||||
rationale behind choices that were made. Exceptions to this policy are
|
||||
technical discussions, that are centered on tools or policies themselves
|
||||
(git, GitHub, c++) rather than on the content of the pull request.
|
||||
|
||||
## GitHub Issues
|
||||
@ -112,39 +113,39 @@ marker in the subject. This is automatically done when using the
|
||||
corresponding template for submitting an issue. Issues may be assigned
|
||||
to one or more developers, if they are working on this feature or
|
||||
working to resolve an issue. Issues that have nobody working
|
||||
on them at the moment or in the near future, have the label
|
||||
on them at the moment, or in the near future, have the label
|
||||
`volunteer needed` attached.
|
||||
|
||||
When an issue, say `#125` is resolved by a specific pull request,
|
||||
the comment for the pull request shall contain the text `closes #125`
|
||||
or `fixes #125`, so that the issue is automatically deleted when
|
||||
the pull request is merged. The template for pull requests includes
|
||||
a header where connections between pull requests and issues can be listed
|
||||
and thus were this comment should be placed.
|
||||
When an issue, say `#125` is resolved by a specific pull request, the
|
||||
comment for the pull request shall contain the text `closes #125` or
|
||||
`fixes #125`, so that the issue is automatically deleted when the pull
|
||||
request is merged. The template for pull requests includes a header
|
||||
where connections between pull requests and issues can be listed, and
|
||||
thus where this comment should be placed.
|
||||
|
||||
## Milestones and Release Planning
|
||||
|
||||
LAMMPS uses a continuous release development model with incremental
|
||||
changes, i.e. significant effort is made - including automated pre-merge
|
||||
testing - that the code in the branch "develop" does not get easily
|
||||
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
|
||||
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
|
||||
developers feel, that a sufficient amount of changes have been included,
|
||||
developers feel, that a sufficient number of changes has 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 with fast forward merges. While "develop" may
|
||||
be temporary broken through issues only detected by the post-merge tests,
|
||||
follows only these versions with fast-forward merges. While "develop" may
|
||||
be temporarily broken through issues only detected by the post-merge tests,
|
||||
The "release" branch is always supposed to be of production quality.
|
||||
|
||||
About once each year, there are going to be "stable" releases of
|
||||
LAMMPS. These have seen additional, manual testing and review of
|
||||
About once each year, there is a "stable" release of LAMMPS.
|
||||
These have seen additional, manual testing and review of
|
||||
results from testing with instrumented code and static code analysis.
|
||||
Also, the last few feature releases before a stable release are "release
|
||||
candidate" versions which only contain bugfixes, feature additions to
|
||||
candidate" versions which only contain bug fixes, feature additions to
|
||||
peripheral functionality, and documentation updates. In between stable
|
||||
releases, bugfixes and infrastructure updates are backported from the
|
||||
releases, bug fixes and infrastructure updates are back-ported from the
|
||||
"develop" branch to the "maintenance" branch and occasionally merged
|
||||
into "stable" and published as update releases.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user