Merge pull request #315 from Pakketeretet2/github-tutorial-update

GitHub tutorial update

doc/src/tutorial_github.txt

@@ -11,10 +11,22 @@ LAMMPS GitHub tutorial :h3
 
 :line
 
-This document briefly describes how to use GitHub to merge changes you
-make into LAMMPS, using GitHub. It assumes that you are familiar with
-git. You may want to have a look at the "Git
-book"_http://git-scm.com/book/ to reacquaint yourself.
+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.
+
+As of fall 2016, submitting contributions to LAMMPS via pull requests
+on GitHub is the preferred option for integrating contributed features
+or improvements to LAMMPS, as it significantly reduces the amount of
+work required by the LAMMPS developers. Consequently, creating a pull
+request will increase your chances to have your contribution included
+and will reduce the time until the integration is complete. For more
+information on the requirements to have your code included into LAMMPS
+please see "Section 10.15"_Section_modify.html#mod_15
 
 :line
 
@@ -30,106 +42,121 @@ username or e-mail address and password.
 
 [Forking the repository]
 
-To get changes into LAMMPS, you need to first fork the repository. At
-the time of writing, LAMMPS-ICMS is the preferred fork. Go to "LAMMPS
-on GitHub"_https://github.com/lammps/lammps and make sure branch is
-set to "lammps-icms", see the figure below.
+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
+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.
 
 :c,image(JPG/tutorial_branch.png)
 
-Now, click on fork in the top right corner:
+If it is not, use the button to change it to {master}. Once it is, use the
+fork button to create a fork.
 
 :c,image(JPG/tutorial_fork.png)
 
-This will create your own fork of the LAMMPS repository. You can make
-changes in this fork and later file {pull requests} to allow the
-upstream repository to merge changes from your own fork into the one
-we just forked from. At the same time, you can set things up, so you
-can include changes from upstream into your repository.
+
+This will create a fork (which is essentially a copy, but uses less
+resources) of the LAMMPS repository under your own GitHub account. You
+can make changes in this fork and later file {pull requests} to allow
+the upstream repository to merge changes from your own fork into the one
+we just forked from (or others that were forked from the same repository).
+At the same time, you can set things up, so you can include changes from
+upstream into your repository and thus keep it in sync with the ongoing
+LAMMPS development.
 
 :line
 
 [Adding changes to your own fork]
 
-Before adding changes, it is better to first create a new branch that
-will contain these changes, a so-called feature branch.
-
-[Feature branches]
-
-Since LAMMPS is such a big project and most user contributions come in
-small portions, the most ideal workflow for LAMMPS is the so-called
-"Feature branch" workflow. It is explained in great detail here:
-"feature branch
+Additions to the upstream version of LAMMPS are handled using {feature
+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.
 
-The idea is that every new feature for LAMMPS gets its own
-branch. This way, it is fairly painless to incorporate new features
-into the upstream repository. I will explain briefly here how to do
-it. In this feature branch, I will add a USER-package.
+[Feature branches]
 
-I assume that git is installed on the local machine and you know how
-to use a command line.
+First of all, create a clone of your version on github on your local
+machine via HTTPS:
 
-First of all, you need to clone your own fork of LAMMPS:
+  $ git clone https://github.com/<your user name>/lammps.git <some name> :pre
 
-  $ git clone https://github.com/<your user name>/lammps.git :pre
+or, if you have set up your GitHub account for using SSH keys, via SSH:
 
-You can find the proper url to the right of the "HTTPS" block, see figure.
+  $ git clone git@github.com:<your user name>/lammps.git :pre
+  
+You can find the proper URL by clicking the "Clone or download"-button:
 
 :c,image(JPG/tutorial_https_block.png)
 
 The above command copies ("clones") the git repository to your local
-machine. You can use this local clone to make changes and test them
-without interfering with the repository on github. First, however, it
-is recommended to make a new branch for a particular feature you would
-like added to LAMMPS. In this example, I will try adding a new
-USER-package called USER-MANIFOLD.
+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.
 
-To create a new branch, run the following git command in your repository:
+You can use this local clone to make changes and
+test them without interfering with the repository on Github.
 
-$ git checkout -b add-user-manifold :pre
+To pull changes from upstream into this copy, you can go to the directory
+and use git pull:
 
-The name of this new branch is "add-user-manifold" in my case. Just
-name it after something that resembles the feature you want added to
-LAMMPS.
+  $ cd mylammps
+  $ git checkout master
+  $ git pull https://github.com/lammps/lammps :pre
 
-Now that you've changed branches, you can edit the files as you see
-fit, add new files, and commit as much as you would like. Just
-remember that if halfway you decide to add another, unrelated feature,
-you should switch branches!
+You can also add this URL as a remote:
 
-After everything is done, add the files to the branch and commit them:
+  $ git remote add lammps_upstream https://www.github.com/lammps/lammps :pre
+
+At this point, you typically make a feature branch from the updated master
+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":
 
-  $ git add src/USER-MANIFOLD examples/USER/manifold/
-  $ git add doc/fix_nv\{t,e\}_manifold_rattle.txt
-  $ git add doc/fix_manifoldforce.txt doc/user_manifolds.txt :pre
+ $ git checkout -b github-tutorial-update master :pre
 
-After the files are added, the change should be comitted:
+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!
 
-  $ git commit -m 'Added user-manifold package' :pre
+[After changes are made]
 
-The "-m" switch is used to add a message to the commit. Use this to
-indicate what type of change was commited.
+After everything is done, add the files to the branch and commit them:
+
+ $ git add doc/src/tutorial_github.txt
+ $ git add doc/src/JPG/tutorial*.png :pre
 
-[Wisdom by Axel]
+IMPORTANT NOTE: Do not use {git commit -a} (or {git add -A}).  The -a
+flag (or -A flag) will automatically include _all_ modified or new files
+and that is rarely the behavior you want.  It can easily lead to
+accidentally adding unrelated and unwanted changes into the repository.
+Instead it is preferable to explicitly use {git add}, {git rm}, {git mv}
+for adding, removing, renaming individual files, respectively, and then
+{git commit} to finalize the commit.  Carefully check all pending
+changes with {git status} before committing them.  If you find doing
+this on the command line too tedious, consider using a GUI, for example
+the one included in git distributions written in Tk, i.e. use {git gui}
+(on some Linux distributions it may be required to install an additional
+package to use it).
 
-{"Do not use "git commit -a".  the -a flag will automatically include
-*all* modified or new files.  mercurial does that and it find it
-hugely annoying and often leading to accidental commits of files you
-don't want.  use git add, git rm, git mv for adding, removing,
-renaming and then git commit to finalize the commit.  personally, i
-find it very convenient to use the bundled gui for commits, i.e. git
-gui.  typically, i will do git add and other operations, but then
-verify and review them with git gui.  git gui also allows to do
-line-by-line unstaging and other convenient operations."}
+After adding all files, the change set can be committed with some
+useful message that explains the change.
+
+  $ git commit -m 'Finally updated the github tutorial' :pre
 
 After the commit, the changes can be pushed to the same branch on GitHub:
 
 $ git push :pre
 
 Git will ask you for your user name and password on GitHub if you have
-not configured anything. If you correctly type your user name and
-password, the change should be added to your fork on GitHub.
+not configured anything. If your local branch is not present on Github yet,
+it will ask you to add it by running
+
+  $ git push --set-upstream origin github-tutorial-update :pre
+
+If you correctly type your user name and
+password, the feature branch should be added to your fork on GitHub.
 
 If you want to make really sure you push to the right repository
 (which is good practice), you can provide it explicitly:
@@ -140,16 +167,20 @@ or using an explicit URL:
 
 $ git push git@github.com:Pakketeretet2/lammps.git :pre
 
-After that, you can file a new pull request based on this
-branch. GitHub will now look like this:
+:line
+
+[Filing a pull request]
 
-:c,image(JPG/tutorial_pull_request_feature_branch1.png)
+Up to this point in the tutorial, all changes were to {your} clones of
+LAMMPS.  Eventually, however, you want this feature to be included into
+the official LAMMPS version.  To do this, you will want to file a pull
+request by clicking on the "New pull request" button:
+
+:c,image(JPG/tutorial_new_pull_request.png)
 
 Make sure that the current branch is set to the correct one, which, in
-this case, is "add-user-manifold". Now click "New pull request". If
-done correctly, the only changes you will see are those that were made
-on this branch, so in my case, I will see nothing related to
-$\mathrm{pair\_dzugatov}.$
+this case, is "github-tutorial-update". If done correctly, the only
+changes you will see are those that were made on this branch.
 
 This will open up a new window that lists changes made to the
 repository. If you are just adding new files, there is not much to do,
@@ -158,36 +189,159 @@ changes in existing files. If all changes can automatically be merged,
 green text at the top will say so and you can click the "Create pull
 request" button, see image.
 
-:c,image(JPG/tutorial_pull_request2.png)
+:c,image(JPG/tutorial_create_new_pull_request1.png)
+
+Before creating the pull request, make sure the short title is accurate
+and add a comment with details about your pull request.  Here you write
+what your modifications do and why they should be incorporated upstream.
 
-After this you have to specify a short title and a comment with
-details about your pull request. I guess here you write what your
-modifications do and why they should be incorporated upstream. After
-that, click the "Create pull request" button, see image below.
+Note the checkbox that says "Allow edits from maintainers".
+This is checked by default checkbox (although in my version of Firefox, only the checkmark is visible):
 
-:c,image(JPG/tutorial_pull_request3.png)
+:c,image(JPG/tutorial_edits_maintainers.png)
 
-Now just write some nice comments, click "Comment", and that is it. It
-is now up to the maintainer(s) of the upstream repository to
-incorporate the changes into the repository and to close the pull
-request.
+If it is checked, maintainers can immediately add their own edits to the
+pull request.  This helps the inclusion of your branch significantly, as
+simple/trivial changes can be added directly to your pull request branch
+by the LAMMPS maintainers.  The alternative would be that they make
+changes on their own version of the branch and file a reverse pull
+request to you.  Just leave this box checked unless you have a very good
+reason not to.
 
-:c,image(JPG/tutorial_pull_request4.png)
+Now just write some nice comments and click on "Create pull request".
+
+:c,image(JPG/tutorial_create_new_pull_request2.png)
 
 :line
 
+[After filing a pull request]
+
+NOTE: When you submit a pull request (or ask for a pull request) for the
+first time, you will receive an invitation to become a LAMMPS project
+collaborator. Please accept this invite as being a collaborator will
+simplify certain administrative tasks and will probably speed up the
+merging of your feature, too.
+
+You will notice that after filing the pull request, some checks are
+performed automatically:
+
+:c,image(JPG/tutorial_automated_checks.png)
+
+If all is fine, you will see this:
+
+:c,image(JPG/tutorial_automated_checks_passed.png)
+
+If any of the checks are failing, your pull request will not be
+processed, as your changes may break compilation for certain
+configurations or may not merge cleanly. It is your responsibility
+to remove the reason(s) for the failed test(s). If you need help
+with this, please contact the LAMMPS developers by adding a comment
+explaining your problems with resolving the failed tests.
+
+A few further interesting things (can) happen to pull requests before
+they are included.
+
 [Additional changes]
 
-Before the pull request is accepted, any additional changes you push
-into your repository will automatically become part of the pull
-request.
+First of all, any additional changes you push into your branch in your
+repository will automatically become part of the pull request:
+
+:c,image(JPG/tutorial_additional_changes.png)
+
+This means you can add changes that should be part of the feature after
+filing the pull request, which is useful in case you have forgotten
+them, or if a developer has requested that something needs to be changed
+before the feature can be accepted into the official LAMMPS version.
+After each push, the automated checks are run again.
+
+[Assignees]
+
+There is an assignee label for pull requests. If the request has not
+been reviewed by any developer yet, it is not assigned to anyone. After
+revision, a developer can choose to assign it to either a) you, b) a
+LAMMPS developer (including him/herself) or c) Steve Plimpton (sjplimp).
+
+Case a) happens if changes are required on your part :ulb,l
+Case b) means that at the moment, it is being tested and reviewed by a
+LAMMPS developer with the expectation that some changes would be required.
+After the review, the developer can choose to implement changes directly
+or suggest them to you. :l
+Case c) means that the pull request has been assigned to the lead
+developer Steve Plimpton and means it is considered ready for merging. :ule,l
+
+In this case, Axel assigned the tutorial to Steve:
+
+:c,image(JPG/tutorial_steve_assignee.png)
+
+[Edits from LAMMPS maintainers]
+
+If you allowed edits from maintainers (the default), any LAMMPS
+maintainer can add changes to your pull request.  In this case, both
+Axel and Richard made changes to the tutorial:
+
+:c,image(JPG/tutorial_changes_others.png)
+
+[Reverse pull requests]
+
+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:
+
+:c,image(JPG/tutorial_reverse_pull_request.png)
+
+For some reason, the highlighted button didn't work in my case, but I
+can go to my own repository and merge the pull request from there:
+
+:c,image(JPG/tutorial_reverse_pull_request2.png)
+
+Be sure to check the changes to see if you agree with them by clicking
+on the tab button:
+
+:c,image(JPG/tutorial_reverse_pull_request3.png)
+
+In this case, most of it is changes in the markup and a short rewrite of
+Axel's explanation of the "git gui" and "git add" commands.
+
+:c,image(JPG/tutorial_reverse_pull_request4.png)
+
+Because the changes are OK with us, we are going to merge by clicking on
+"Merge pull request".  After a merge it looks like this:
+
+:c,image(JPG/tutorial_reverse_pull_request5.png)
+
+Now, since in the meantime our local text for the tutorial also changed,
+we need to pull Axel's change back into our branch, and merge them:
+
+ $ git add tutorial_github.txt
+ $ git add JPG/tutorial_reverse_pull_request*.png
+ $ git commit -m "Updated text and images on reverse pull requests"
+ $ git pull :pre
+
+In this case, the merge was painless because git could auto-merge:
+
+:c,image(JPG/tutorial_reverse_pull_request6.png)
+
+With Axel's changes merged in and some final text updates, our feature
+branch is now perfect as far as we are concerned, so we are going to
+commit and push again:
+
+ $ git add tutorial_github.txt
+ $ git add JPG/tutorial_reverse_pull_request6.png
+ $ git commit -m "Merged Axel's suggestions and updated text"
+ $ git push git@github.com:Pakketeretet2/lammps :pre
+
 
 :line
 
 [After a merge]
 
-When everything is fine the feature branch is merged into the LAMMPS
-repositories:
+When everything is fine, the feature branch is merged into the master branch.
 
 :c,image(JPG/tutorial_merged.png)
 
@@ -198,17 +352,29 @@ It is in principle safe to delete them from your own fork. This helps
 keep it a bit more tidy. Note that you first have to switch to another
 branch!
 
-$ git checkout lammps-icms
-$ git pull lammps-icms
-$ git branch -d add-user-manifold :pre
+$ git checkout master
+$ git pull master
+$ git branch -d github-tutorial-update :pre
 
 If you do not pull first, it is not really a problem but git will warn
 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-icms upstream. If you
+know your branch just got merged into LAMMPS upstream. If you
 first delete and then pull, everything should still be fine.
 
 Finally, if you delete the branch locally, you might want to push this
 to your remote(s) as well:
 
-$ git push origin :add-user-manifold :pre
+$ git push origin :github-tutorial-update :pre
+
+[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.