[gentoo-commits] proj/sci:master commit in: /

[Sebastien Fabbro]

commit:     5dcfbeaf5f310bc47e909acef735b2b877c597a3
Author:     Justin Lecher <jlec <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 26 09:17:44 2014 +0000
Commit:     Sebastien Fabbro <bicatali <AT> gentoo <DOT> org>
CommitDate: Sun Jan 26 09:17:44 2014 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/sci.git;a=commit;h=5dcfbeaf

Vastely update and rewrite the text
Include commends from bicatali

Signed-off-by: Justin Lecher <jlec <AT> gentoo.org>

---
 CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 53 insertions(+), 20 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f47e97..7da80ca 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,16 +1,27 @@
 #Contributions to the Gentoo Science Overlay
 
+This guide summerizes the contribution and merging procedures for the Gentoo Science overlay on Github. For more information please visit the [Science Project page](https://wiki.gentoo.org/wiki/Project:Science/Contributing) in the [Gentoo wiki](https://wiki.gentoo.org/).
+
 ----
 ##Prerequisite
+For the most convinient way to work with the overlay you should fulfill all prerequisites.
 
 ###Required
 
+* **Install git**
+
+The Science overlay is controlled by [git](http://git-scm.com/). You can install it with
+
+    emerge dev-vcs/git
+
+Familiarize yourself with git and visit [http://git-scm.com/documentation](http://git-scm.com/documentation) for documentation.
+
 * **Account at [github](https://github.com/join)**
 
-Everybody who wants to contribute needs to own an account. Please register yourself there.
+Everybody who wants to contribute needs to own an account @ [Github](http://github.com/). Please register yourself [there](https://github.com/join).
 
 ###Recommended
-* **Define echangelog user**
+* **Define the echangelog user**
 
 Make sure the ECHANGELOG_USER variable is present in your environment.
 
@@ -23,58 +34,69 @@ Create a [gpg key](http://www.gossamer-threads.com/lists/gentoo/dev/268496?do=po
 
     git config --global user.signingkey <gpg-key-id>
 
+Now git will sign your commits to the overlay by using the gpg key.
 
-* **Install [hub](http://hub.github.com/)**, the "command-line wrapper for git that makes you better at GitHub".
+* **Install [hub](http://hub.github.com/)**, the *command-line wrapper for git that makes you better at GitHub*.
 
-This file will use *hub* because of it's convenience when working with github.
+*hub* can be used equivalent to to *git* and upstream even recommends *"alias git='hub'*.
 
     emerge dev-vcs/hub
 
+* **Install [repo-commit](https://bitbucket.org/gentoo/repo-commit/)**, *A repository commit helper*
 
-----
-##For Contributors
+*repo-commit* sanitizes your commit in a convinient way.
 
+    emerge app-portage/repo-commit
 
-First clone the overlay
+---
+##Contributing ebuilds
 
-    hub clone gentoo-science/sci
+###Clone the overlay
 
+Create a local checkout of the overlay
 
+    hub clone gentoo-science/sci
+
+###Fork the overlay
 In order to send pull request and ask for inclusion of your changes you need to have your own fork of the overlay on github. You can do this by issuing
 
     cd sci
     hub fork
 
-Now you are ready to start your work.
-
+###Branch out for contribution
 It is always convenient for development as well as for the review and merging process, if the development is done in branches.
 
     git checkout -b my-feature master
 
-Now you can work on you package of interest. Once you are finished you should _always_ use **[repoman](http://dev.gentoo.org/~zmedico/portage/doc/man/repoman.1.html)** to check, verify and commit your changes.
+###Work on the package
+Now you are ready to work on your package of interest. Once you are finished you should _always_ use **[repoman](http://dev.gentoo.org/~zmedico/portage/doc/man/repoman.1.html)** to do a statical analysis of your work.
 
-Static analysis can be done with
+This can be done with
 
     repoman full
 
+###Commit your work
 Once *all* reported problems are resolved, you can commit it
 
-    echangelog "Here we write a comprehensible ChangeLog message"
-    repoman -m "Here we write a comprehensible commit message" commit
+    repo-commit "Here we write a comprehensible commit message"
 
+###Push to Github and make a pull request
 Next we push back the changes to our fork and send a pull-request to the overlay maintainers.
 
     hub push YOUR_GITHUB_USER
     hub pull-request
 
-Lastly you need to wait for review comments and the merge of your work. In case you need to include some improvements, just commit your work again using repoman and push it again to your fork. No need to send another pull-request as your new changes will be added to the original one.
+Lastly you need to wait for review comments and the merge of your work. If you feel that they are slacking, don't bother to ping them again. In case you need to include some improvements, just commit your work again using *repo-commit* and push it again to your fork. No need to send another pull-request as your new changes will be added to the original one.
+
+###What's next?
+If you would like to get direct access to the overlay, prove some contribution and ping us via sci@g.o or on irc in #gentoo-science @ freenode. If you would like to become a dev yourself, prove some more contributions and again, contact us. We are always looking for new candidates.
 
 ----
-##For Maintainers
+##Merging contributions
+
+**It is important, that if you merge a pull request, you should feel as responsible as if you have written the commits yourself!**
 
-**The merging of pull request should only be done by gentoo developers!**
 
-If you feel that they are slacking, don't bother to ping them again. If you would like to become a dev yourself, prove some contribution and ping us via sci@g.o or on irc in #gentoo-science @ freenode.
 
 ###Prerequisite
 
@@ -93,21 +115,32 @@ should give
 >origin	git+ssh://git@×××××××××××××××××××.org/proj/sci.git (push)
 
 
-In the beginning you should review the pull request on github directly and recommend as much improvements as possible. Once everything is fine or you like to fix the rest yourself, simply can use the follow command to get the pull-request in a new branch in you repo.
+###Review process
+
+In the beginning you should review the pull request on github directly and recommend as much improvements as possible. By this you train the new contributor towards becoming a new dev, which should be our final goal.
+
+####Checking out the pull-request as local branch
+Once everything is fine or you like to fix the rest yourself, simply use the following command to get the pull-request in a new branch in your repo.
 
     hub checkout https://github.com/gentoo-science/sci/pull/PULLREQUEST-NUMBER
 
-Now check the package by building and installing it, and run *repoman* in the package dir. If this is also fine, merge the branch into the master
+####Testing and repoman check
+Now check the package by building and installing it, and run *repoman* in the package dir. Remember, when merging a pull request you take the responsibility for the quality of the commit.
+
+####Merge the pull-request branch into master
+If this is also fine, merge the branch into the master
 
     git checkout master
     git merge USER-BRANCH
 
+####Merging the two remote HEADs
 Finally use the script **merge-dualHEAD** from the *scripts* directory to merge the github and gentoo.org remote repo.
 
 
 ---
 ####Contribution to the document
 Sebastien Fabbro <bicatali@g.o>
+
 Justin Lecher <jlec@g.o>
 
 This document is available under [Creative Commons Attribution ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0)