fix name
[dealii.wiki.git] / Contributing.md
index c640c2b0aa0eb3749ec78ed9d70dd7aac9ca76a9..cd64e339a443598ca8cc33e1d6d78ade5f4ee102 100644 (file)
@@ -1,6 +1,8 @@
 # Contributing code via Git and GitHub
 
-deal.II is developed using [Git](https://git-scm.com) as a version control tool, [GitHub](https://github.com/about) as the central source-code host and a [branch-based workflow](https://guides.github.com/introduction/flow/). This article supplements the information given in the [CONTRIBUTING](https://github.com/dealii/dealii/blob/master/CONTRIBUTING.md) documentation and this [video lecture](http://www.math.colostate.edu/%7Ebangerth/videos.676.32.8.html).
+deal.II is developed using [Git](https://git-scm.com) as a version control tool, [GitHub](https://github.com/about) as the central source-code host and a [branch-based workflow](https://guides.github.com/introduction/flow/). This article supplements the information given in the [CONTRIBUTING](https://github.com/dealii/dealii/blob/master/CONTRIBUTING.md) documentation and this [detailed video lecture](http://www.math.colostate.edu/%7Ebangerth/videos.676.32.8.html).
+
+## The basic steps
 
 To contribute a patch back to the project (which we greatly appreciate), the following summarises the steps that you need to take to do this:
 
@@ -13,6 +15,8 @@ To contribute a patch back to the project (which we greatly appreciate), the fol
 5. When you're finished committing all of your changes to your local repository, you can push them all upstream to your Github repository.
 6. Now you're set to open a pull request, which is typically done from GitHub's website. Once you've done this one or more of the principal developers, or fellow members of the community, may review your changes and engage you on them. We may then go through a (hopefully succinct) stage of iterating your developments until all parties are satisfied with the proposed changes. After this the project, incorporating the proposed modifications, will be built and tested on a remote machine to check that the additions to not break any existing functionality. If these final tests pass then your feature branch will be merged by one of the principal developers.
 
+## An example
+
 Using the command line, steps 2-5 would be achieved in the following manner:
 
 2. Clone the forked repository
@@ -76,12 +80,12 @@ index 733e289308..1564ac6e5c 100644
  Further information:
  --------------------
 ```
-Here we fixed a typographical error, a small but valuable contribution!
+Here we fixed a typographical error - a small but valuable contribution!
 At this point it appears that we're ready to inform Git of the changes that we've made, but remember the styling that deal.II expects? We should first ensure that our changes adheres to them.
 ```sh
-$ ./contrib/utilities/indent # Called from the base deal.II directory.
+$ ./contrib/utilities/indent # Called from the base directory.
 ```
-The next step is to add these changes to Git's index, which is reflected in a change in status of these two files.
+The next step is to add these changes to Git's index (_staging_), which is reflected in a change in status of these two files.
 ```sh
 $ git add README.md MORE_DOCUMENTATION.md # Add to the index the current state of these files
 $ git status
@@ -103,7 +107,7 @@ You can see that your branch differs from the `master` branch. We can also inspe
 ```sh
 $ git log -n 1 # Show the last entry in the history
 commit a4f12d6ee26f3fefab24c758807261cd91f2a46e
-Author: Jean-Paul Pelteret
+Author: <Author's name> <Author's email address>
 Date:   Sat Nov 11 16:25:26 2017 +0100
 
     A short description of my changes
@@ -116,7 +120,14 @@ In this example commit, we've used two keywords that show that upon merging issu
 ```sh
 $ git push -u origin my_amazing_new_feature # Push a specified branch to the specified remote destination
 ```
-In particular, this tells Git to synchronize (or create) the branch `my_amazing_new_feature` on the remote repository labelled `origin`.  
+In particular, this tells Git to synchronize (or create) the branch `my_amazing_new_feature` on the remote repository labelled `origin`. We could also verify exactly where `origin` points before pushing our changes:
+```sh
+$ git remote -vv
+origin git@github.com:<username>/dealii.git (fetch)
+origin git@github.com:<username>/dealii.git (push)
+```
+
+## Further information
 
 There's also a tool called [`hub`](https://github.com/github/hub) that facilitates interactions with GitHub (e.g. forking a repository, opening pull requests) from the command line.
 

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.