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

update documentation to refer to the new branch names (develop, release)

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-10-10 04:39:16 -04:00
parent ba44d6aba2
commit eb6b73c752
6 changed files with 123 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Build_diskspace.rst
View File

@ -14,7 +14,7 @@ environments with restricted disk space capacity it may be needed to
reduce the storage requirements. Here are some suggestions:
- Create a so-called shallow repository by cloning only the last commit
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=master``.
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=develop``.
This reduces the downloaded size to about half. With ``--depth=1`` it is not possible to check out different
versions/branches of LAMMPS, using ``--depth=1000`` will make multiple recent versions available at little
extra storage needs (the entire git history had nearly 30,000 commits in fall 2021).

15
doc/src/Build_manual.rst
View File

@ -33,12 +33,15 @@ 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, aka unstable
branch) is is available online at:
`https://docs.lammps.org/Manual.html <https://docs.lammps.org/Manual.html>`_.
A version of the manual corresponding to the ongoing development (aka master branch)
is available online at: `https://docs.lammps.org/latest/
<https://docs.lammps.org/latest/>`_
A current version of the manual (latest patch 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
the state of the *develop* branch) is available online at:
`https://docs.lammps.org/latest/ <https://docs.lammps.org/latest/>`_
A version of the manual corresponding to the latest stable LAMMPS release
(that is the state of the *stable* branch) is available online at:
`https://docs.lammps.org/stable/ <https://docs.lammps.org/stable/>`_
Build using GNU make
--------------------

133
doc/src/Howto_github.rst
View File

@ -7,11 +7,11 @@ LAMMPS GitHub tutorial
This document describes the process of how to use GitHub to integrate
changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as
an example to describe the individual steps and options. You need to
be familiar with git and you may want to have a look at the
`git book <http://git-scm.com/book/>`_ to reacquaint yourself with some
of the more advanced git features used below.
distribution. It uses the process of updating this very tutorial as an
example to describe the individual steps and options. You need to be
familiar with git and you may want to have a look at the `git book
<http://git-scm.com/book/>`_ to familiarize yourself with some of the
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
on GitHub is the preferred option for integrating contributed features
@ -37,15 +37,15 @@ username or e-mail address and password.
**Forking the repository**
To get changes into LAMMPS, you need to first fork the `lammps/lammps`
repository on GitHub. At the time of writing, *master* is the preferred
repository on GitHub. At the time of writing, *develop* is the preferred
target branch. Thus go to `LAMMPS on GitHub <https://github.com/lammps/lammps>`_
and make sure branch is set to "master", as shown in the figure below.
and make sure branch is set to "develop", as shown in the figure below.
.. image:: JPG/tutorial_branch.png
:align: center
If it is not, use the button to change it to *master*\ . Once it is, use the
fork button to create a fork.
If it is not, use the button to change it to *develop*. Once it is, use
the fork button to create a fork.
.. image:: JPG/tutorial_fork.png
:align: center
@ -64,11 +64,12 @@ LAMMPS development.
**Adding changes to your own fork**
Additions to the upstream version of LAMMPS are handled using *feature
branches*\ . For every new feature, a so-called feature branch is
branches*. For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else. It is
explained in more detail here: `feature branch workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
explained in more detail here: `feature branch workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
**Feature branches**
@ -94,8 +95,8 @@ The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.
You can use this local clone to make changes and
test them without interfering with the repository on GitHub.
You can use this local clone to make changes and test them without
interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
@ -103,28 +104,45 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
$ git remote add lammps_upstream https://www.github.com/lammps/lammps
$ git remote add upstream https://www.github.com/lammps/lammps
At this point, you typically make a feature branch from the updated master
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
At this point, you typically make a feature branch from the updated
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":
.. code-block:: bash
$ git checkout -b github-tutorial-update master
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!
.. note::
Committing changes to the *develop*, *release*, or *stable* branches
is strongly discouraged. While it may be convenient initially, it
will create more work in the long run. Various texts and tutorials
on using git effectively discuss the motivation for this.
**After changes are made**
After everything is done, add the files to the branch and commit them:
@ -287,28 +305,32 @@ After each push, the automated checks are run again.
LAMMPS developers may add labels to your pull request to assign it to
categories (mostly for bookkeeping purposes), but a few of them are
important: needs_work, work_in_progress, test-for-regression, and
full-regression-test. The first two indicate, that your pull request
is not considered to be complete. With "needs_work" the burden is on
exclusively on you; while "work_in_progress" can also mean, that a
LAMMPS developer may want to add changes. Please watch the comments
to the pull requests. The two "test" labels are used to trigger
extended tests before the code is merged. This is sometimes done by
LAMMPS developers, if they suspect that there may be some subtle
side effects from your changes. It is not done by default, because
those tests are very time consuming.
important: *needs_work*, *work_in_progress*, *run_tests*,
*test_for_regression*, and *ready_for_merge*. The first two indicate,
that your pull request is not considered to be complete. With
"needs_work" the burden is on exclusively on you; while
"work_in_progress" can also mean, that a LAMMPS developer may want to
add changes. Please watch the comments to the pull requests. The two
"test" labels are used to trigger extended tests before the code is
merged. This is sometimes done by LAMMPS developers, if they suspect
that there may be some subtle side effects from your changes. It is not
done by default, because those tests are very time consuming. The
*ready_for_merge* label is usually attached when the LAMMPS developer
assigned to the pull request considers this request complete and to
trigger a final full test evaluation.
**Reviews**
As of Summer 2018, a pull request needs at least 1 approving review
from a LAMMPS developer with write access to the repository.
In case your changes touch code that certain developers are associated
with, they are auto-requested by the GitHub software. Those associations
are set in the file
`.github/CODEOWNERS <https://github.com/lammps/lammps/blob/master/.github/CODEOWNERS>`_
Thus if you want to be automatically notified to review when anybody
changes files or packages, that you have contributed to LAMMPS, you can
add suitable patterns to that file, or a LAMMPS developer may add you.
As of Fall 2021, a pull request needs to pass all automatic tests and at
least 1 approving review from a LAMMPS developer with write access to
the repository before it is eligible for merging. In case your changes
touch code that certain developers are associated with, they are
auto-requested by the GitHub software. Those associations are set in
the file `.github/CODEOWNERS
<https://github.com/lammps/lammps/blob/develop/.github/CODEOWNERS>`_ Thus
if you want to be automatically notified to review when anybody changes
files or packages, that **you** have contributed to LAMMPS, you can add
suitable patterns to that file, or a LAMMPS developer may add you.
Otherwise, you can also manually request reviews from specific developers,
or LAMMPS developers - in their assessment of your pull request - may
@ -329,7 +351,7 @@ LAMMPS developer (including him/herself) or c) Axel Kohlmeyer (akohlmey).
After the review, the developer can choose to implement changes directly
or suggest them to you.
* Case c) means that the pull request has been assigned to the developer
overseeing the merging of pull requests into the master branch.
overseeing the merging of pull requests into the *develop* branch.
In this case, Axel assigned the tutorial to Steve:
@ -351,11 +373,11 @@ Sometimes, however, you might not feel comfortable having other people
push changes into your own branch, or maybe the maintainers are not sure
their idea was the right one. In such a case, they can make changes,
reassign you as the assignee, and file a "reverse pull request", i.e.
file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that
case, you can choose to merge their changes back into your branch,
possibly make additional changes or corrections and proceed from there.
It looks something like this:
file a pull request in **your** forked GitHub repository to include
changes in the branch, that you have submitted as a pull request
yourself. In that case, you can choose to merge their changes back into
your branch, possibly make additional changes or corrections and proceed
from there. It looks something like this:
.. image:: JPG/tutorial_reverse_pull_request.png
:align: center
@ -419,7 +441,7 @@ This merge also shows up on the lammps GitHub page:
**After a merge**
When everything is fine, the feature branch is merged into the master branch:
When everything is fine, the feature branch is merged into the *develop* branch:
.. image:: JPG/tutorial_merged.png
:align: center
@ -433,8 +455,8 @@ branch!
.. code-block:: bash
$ git checkout master
$ git pull master
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
@ -442,6 +464,7 @@ you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into LAMMPS upstream. If you
first delete and then pull, everything should still be fine.
You can display all branches that are fully merged by:
Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:
@ -453,14 +476,14 @@ 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 master branch, to which all new features
should be submitted, there is now also an "unstable" and a "stable"
branch; these have the same content as "master", 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.
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.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/master/doc/github-development-workflow.md>`_
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

47
doc/src/Install_git.rst
View File

@ -9,7 +9,8 @@ has several advantages:
command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
LAMMPS.
LAMMPS. For that you should first create your own :doc:`fork on
GitHub <Howto_github>`.
You must have `git <git_>`_ installed on your system to use the
commands explained below to communicate with the git servers on
@ -20,35 +21,53 @@ provides `limited support for subversion clients <svn_>`_.
As of October 2016, the official home of public LAMMPS development is
on GitHub. The previously advertised LAMMPS git repositories on
git.lammps.org and bitbucket.org are now deprecated or offline.
git.lammps.org and bitbucket.org are now offline or deprecated.
.. _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 LAMMPS development on 3 different git branches:
You can follow the LAMMPS development on 3 different git branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
* **stable** : this branch is updated with every stable release;
updates are always "fast forward" merges from *develop*
* **release** : this branch is updated with every patch 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
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:
.. code-block:: bash
$ git clone -b unstable https://github.com/lammps/lammps.git mylammps
$ git clone -b release https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
your machine and "release" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)
.. note::
The complete git history of the LAMMPS project is quite large because
it contains the entire commit history of the project since fall 2006,
which includes the time when LAMMPS was managed with subversion. This
also includes commits that have added and removed some large files
(mostly by accident). If you do not need access to the entire commit
history, you can speed up the "cloning" process and reduce local disk
space requirements by using the *--depth* git command line flag thus
create a "shallow clone" of the repository that 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.
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.
Or 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
@ -56,9 +75,9 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout unstable # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout master # to choose the branch to follow
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout develop # to choose the branch to follow
$ git pull
Doing a "pull" will not change any files you have added to the LAMMPS
@ -81,7 +100,7 @@ Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout unstable`` (or
again, you will need to do ``git checkout release`` (or
check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git

2
doc/src/Intro_opensource.rst
View File

@ -19,7 +19,7 @@ software and open-source distribution, see `www.gnu.org <gnuorg_>`_
or `www.opensource.org <opensource_>`_. The legal text of the GPL as it
applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _gpl: https://github.com/lammps/lammps/blob/master/LICENSE
.. _gpl: https://github.com/lammps/lammps/blob/develop/LICENSE
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html

2
doc/src/Manual_version.rst
View File

@ -7,7 +7,7 @@ correctly and reliably at all times. You can follow its development
in a public `git repository on GitHub <https://github.com/lammps/lammps>`_.
Whenever we fix a bug or update or add a feature, it will be merged into
the `master` branch of the git repository. When a sufficient number of
the *develop* branch of the git repository. When a sufficient number of
changes have accumulated *and* the software passes a set of automated
tests, we release it in the next *patch* release, which are made every
few weeks. Info on patch releases are on `this website page