Contributing guide Improvement Fix rucio#331

CONTRIBUTING.rst

@@ -42,23 +42,55 @@ Contributing
 
 **Step 1**: Create an `issue <https://github.com/rucio/rucio/issues/new>`_ with the description
 of the contribution (motivation, modification and expected results).
-Every issue will get a **unique issue number**.
+Every issue will get a **unique issue number**. Valid component names are
+listed in the `label list <https://github.com/rucio/rucio/labels>`_.
 
 **Step 2**: Create a local branch that corresponds to the issue. There are utility scripts to help you with this::
 
-  $ ./tools/create-patch-branch <unique issue number> '<component> #<issue number>: <short_change_message>'
-  $ ./tools/create-feature-branch <unique issue number> '<component> #<issue number>: <short_change_message>'
+  $ ./tools/create-patch-branch <unique issue number> '<short_change_message>'
+  $ ./tools/create-feature-branch <unique issue number> '<short_change_message>'
 
 **Step 3**: Commit your change. The format of the commit message must be::
 
 <component>: <change_message> #<issue number>
 
-Valid component names are listed in the `label list <https://github.com/rucio/rucio/labels>`_
+Valid component names are listed in the `label list <https://github.com/rucio/rucio/labels>`_.
+
+If you add a `github-recognised keyword <https://help.github.com/articles/closing-issues-using-keywords/>`_ then
+the associated issue can be closed automatically once the pull request is merged, e.g.::
+
+    <component>: <short_change_message> Fix #<issue number>
 
 **Step 4**: Push the commit to your forked repository and create the pull request(s). There is a helper script to assist you::
 
   $ ./tools/submit-pull-request
 
+The helper script will propagate the commit message as the pull request title.
+
+If you use different tools to create pull requests like the `github interface <https://help.github.com/articles/creating-a-pull-request/>`_
+or the git command-line wrapper `hub <https://hub.github.com>`_, the following logic must be applied:
+ * If the contribution is a **patch**, the pull request must go against the **next** and the **master** branch.
+ * If the contribution is a new **feature**, the pull request must go against the **next** branch.
+
+The format of the pull request title must be:
+
+    <component>: <short_change_message> #<issue number>
+
+If you add a `github-recognised keyword <https://help.github.com/articles/closing-issues-using-keywords/>`_ then
+the associated issue can be closed automatically once the pull request is merged, e.g.::
+
+<short_change_message> Fix #<issue number>
+
+For example, with `hub the git command-line wrapper <https://hub.github.com>`_ it would be for
+a **patch**::
+
+  $  git pull-request  -m  '<component>: <short_change_message> #<issue number>' -b master
+  $  git pull-request  -m  '<component>: <short_change_message> #<issue number>' -b next
+
+and for a new **feature**::
+
+  $  git pull-request  -m  '<short_change_message> #<issue number>' -b next
+
 **Step 5**: Watch the pull request for comments and reviews. For any pull requests update,
 please try to squash/amend your commits to avoid "in-between" commits.
 

PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,9 @@ The format of the Pull request title must be:
 
     <component>: <short_change_message> #<issue number>
 
-Possibly with a [keyword](https://help.github.com/articles/closing-issues-using-keywords/) to close issue
-automatically when the Pull request is merged. e.g.:
+If you add a [github-recognised keyword](https://help.github.com/articles/closing-issues-using-keywords/) then
+the associated issue can be closed automatically once the pull request is merged, e.g.::
 
     <component>: <short_change_message> Fix #<issue number>
+
+Valid component names are listed in the `label list <https://github.com/rucio/rucio/labels>`_.