polish the introduction, some more clarifications, corrections and formatting improvements

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
+This document describes the process of how to use GitHub to integrate
-make into LAMMPS, using GitHub. It assumes that you are familiar with
+changes or additions you have made to LAMMPS into the official LAMMPS
-git. You may want to have a look at the "Git
+distribution.  It uses the process of updating this very tutorial as
-book"_http://git-scm.com/book/ to reacquaint yourself.
+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,24 +42,27 @@ username or e-mail address and password.
 
 [Forking the repository]
 
-To get changes into LAMMPS, you need to first fork the repository. At
+To get changes into LAMMPS, you need to first fork the `lammps/lammps`
-the time of writing, master is the preferred branch. Go to "LAMMPS
+repository on GitHub. At the time of writing, {master} is the preferred
-on GitHub"_https://github.com/lammps/lammps and make sure branch is
+target branch. Thus go to "LAMMPS on GitHub"_https://github.com/lammps/lammps
-set to "master", see the figure below.
+and make sure branch is set to "master", as shown in the figure below.
 
 :c,image(JPG/tutorial_branch.png)
 
-If it is not, use the button to change it to master. Once it is, use the
+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
+This will create a fork (which is essentially a copy, but uses less
-changes in this fork and later file {pull requests} to allow the
+resources) of the LAMMPS repository under your own GitHub account. You
-upstream repository to merge changes from your own fork into the one
+can make changes in this fork and later file {pull requests} to allow
-we just forked from. At the same time, you can set things up, so you
+the upstream repository to merge changes from your own fork into the one
-can include changes from upstream into your repository.
+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
 
@@ -64,15 +79,15 @@ workflow"_https://www.atlassian.com/git/tutorials/comparing-workflows/feature-br
 [Feature branches]
 
 First of all, create a clone of your version on github on your local
-machine via HTTPS
+machine via HTTPS:
 
   $ git clone https://github.com/<your user name>/lammps.git <some name> :pre
 
-or, if you have SSH keys setup, using your SSH key:
+or, if you have set up your GitHub account for using SSH keys, via SSH:
 
   $ git clone git@github.com:<your user name>/lammps.git :pre
   
-You can find the proper url by clicking the "Clone or download"-button:
+You can find the proper URL by clicking the "Clone or download"-button:
 
 :c,image(JPG/tutorial_https_block.png)
 
@@ -90,7 +105,7 @@ and use git pull:
   $ git checkout master
   $ git pull https://github.com/lammps/lammps :pre
 
-You can also add this url as a remote:
+You can also add this URL as a remote:
 
   $ git remote add lammps_upstream https://www.github.com/lammps/lammps :pre
 
@@ -99,7 +114,7 @@ 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 checkout -b github-tutorial-update master :pre
+ $ git checkout -b github-tutorial-update master :pre
 
 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,
@@ -109,19 +124,21 @@ unrelated feature, you should switch branches!
 
 After everything is done, add the files to the branch and commit them:
 
-  $ git add doc/src/tutorial_github.txt
+ $ git add doc/src/tutorial_github.txt
-  $ git add doc/src/JPG/tutorial_*.png :pre
+ $ git add doc/src/JPG/tutorial*.png :pre
 
-IMPORTANT NOTE: Do not use `git commit -a`.  The -a flag will
+IMPORTANT NOTE: Do not use {git commit -a} (or {git add -A}).  The -a
-automatically include _all_ modified or new files and that is rarely the
+flag (or -A flag) will automatically include _all_ modified or new files
-behavior you want.  It can easily lead to accidentally adding unrelated
+and that is rarely the behavior you want.  It can easily lead to
-and unwanted changes into the repository.  Instead it is preferable to
+accidentally adding unrelated and unwanted changes into the repository.
-explicitly use `git add`, `git rm`, `git mv` for adding, removing,
+Instead it is preferable to explicitly use {git add}, {git rm}, {git mv}
-renaming files, respectively, and then `git commit` to finalize the
+for adding, removing, renaming individual files, respectively, and then
-commit.  If you find doing this on the command line too tedious,
+{git commit} to finalize the commit.  Carefully check all pending
-consider using a GUI, for example the one included in git distributions
+changes with {git status} before committing them.  If you find doing
-written in Tk, i.e. use `git gui` (on some Linux distributions it may
+this on the command line too tedious, consider using a GUI, for example
-be required to install an additional package to use it).
+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).
 
 After adding all files, the change set can be committed with some
 useful message that explains the change.
@@ -150,12 +167,14 @@ or using an explicit URL:
 
 $ git push git@github.com:Pakketeretet2/lammps.git :pre
 
+:line
+
 [Filing a pull request]
 
-Up to this point in the tutorial, all changes were to {your} clones of LAMMPS.
+Up to this point in the tutorial, all changes were to {your} clones of
-Eventually, however, you want this feature to be included again upstream.
+LAMMPS.  Eventually, however, you want this feature to be included into
-To do this, you will want to file a pull request by clicking on the
+the official LAMMPS version.  To do this, you will want to file a pull
-"New pull request" button:
+request by clicking on the "New pull request" button:
 
 :c,image(JPG/tutorial_new_pull_request.png)
 
@@ -173,19 +192,21 @@ request" button, see image.
 :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.
+and add a comment with details about your pull request.  Here you write
-I guess here you write what your modifications do and why they should
+what your modifications do and why they should be incorporated upstream.
-be incorporated upstream.
 
 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_edits_maintainers.png)
 
-If it is checked, maintainers can immediately add their own edits to the pull request.
+If it is checked, maintainers can immediately add their own edits to the
-This helps the inclusion of your branch significantly, as simple/trivial changes can be made by the maintainers directly.
+pull request.  This helps the inclusion of your branch significantly, as
-The alternative would be that they make changes on their own version of the branch and file a reverse pull request to you.
+simple/trivial changes can be added directly to your pull request branch
-Just leave this box checked unless you have a very good reason not to.
+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.
 
 Now just write some nice comments and click on "Create pull request".
 
@@ -195,11 +216,14 @@ Now just write some nice comments and click on "Create pull request".
 
 [After filing a pull request]
 
-NOTE: When you submit a pull request (or ask for a pull request), you will receive an
+NOTE: When you submit a pull request (or ask for a pull request) for the
-invitation to become a LAMMPS project collaborator. This will simplify certain
+first time, you will receive an invitation to become a LAMMPS project
-administrative tasks and will probably speed up the merging of your feature.
+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:
+You will notice that after filing the pull request, some checks are
+performed automatically:
 
 :c,image(JPG/tutorial_automated_checks.png)
 
@@ -207,7 +231,15 @@ If all is fine, you will see this:
 
 :c,image(JPG/tutorial_automated_checks_passed.png)
 
-A few further interesting things (can) happen to pull requests before they are included.
+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]
 
@@ -218,9 +250,9 @@ repository will automatically become part of the pull request:
 
 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 ruled that something needs to change before
+them, or if a developer has requested that something needs to be changed
-the feature can be accepted upstream.  After each push, the automated
+before the feature can be accepted into the official LAMMPS version.
-checks are run again.
+After each push, the automated checks are run again.
 
 [Assignees]
 
@@ -231,11 +263,11 @@ 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.  After review, the developer can choose to implement
+LAMMPS developer with the expectation that some changes would be required.
-changes or suggest them to you. :l
+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
+developer Steve Plimpton and means it is considered ready for merging. :ule,l
-merging. :ule,l
 
 In this case, Axel assigned the tutorial to Steve:
 
@@ -243,42 +275,48 @@ In this case, Axel assigned the tutorial to Steve:
 
 [Edits from LAMMPS maintainers]
 
-If you allowed edits from maintainers (the default), any LAMMPS maintainer can add changes to your pull request.
+If you allowed edits from maintainers (the default), any LAMMPS
-In this case, both Axel and Richard made changes to the tutorial:
+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,
+Sometimes, however, you might not feel comfortable having other people
-or maybe the maintainers are not sure their idea was the right one.
+push changes into your own branch, or maybe the maintainers are not sure
-In such a case, they can make changes, reassign you as the assignee, and file a reverse pull request.
+their idea was the right one.  In such a case, they can make changes,
-In that case, you can choose to merge their changes back into your branch, and proceed from there.
+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
+For some reason, the highlighted button didn't work in my case, but I
-repository and merge the pull request from there:
+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:
+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
+In this case, most of it is changes in the markup and a short rewrite of
-of the "git gui" and "git add" commands.
+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".
+Because the changes are OK with us, we are going to merge by clicking on
-After a merge it looks like this:
+"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
+Now, since in the meantime our local text for the tutorial also changed,
-Axel's change back into our branch, and merge them:
+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
@@ -289,8 +327,9 @@ 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
+With Axel's changes merged in and some final text updates, our feature
-now perfect as far as we are concerned, so we are going to commit and push again:
+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
@@ -320,7 +359,7 @@ $ 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
@@ -330,12 +369,12 @@ $ git push origin :github-tutorial-update :pre
 
 [Recent changes in the workflow]
 
-Some changes to the workflow are not captured in this tutorial.
+Some changes to the workflow are not captured in this tutorial.  For
-For example, in addition to the master branch, to which all
+example, in addition to the master branch, to which all new features
-new features should be submitted, there is now also an "unstable"
+should be submitted, there is now also an "unstable" and a "stable"
-and a "stable" branch. Furthermore, the naming of the patches
+branch; these have the same content as "master", but are only updated
-now follow the pattern "patch_<Day><Month><Year>" so simplify
+after a patch release or stable release was made.
-comparisons between releases.
+Furthermore, the naming of the patches now follow the pattern
-Finally, all patches and submissions are subject to automatic
+"patch_<Day><Month><Year>" to simplify comparisons between releases.
-testing and code checks to make sure they at the very least
+Finally, all patches and submissions are subject to automatic testing
-compile.
+and code checks to make sure they at the very least compile.