docs: improve the contributing section

* Rephrased some paragraphs
* Better organised the section itself
* Added guideline and formatting examples for commit log messages

Signed-off-by: Hugo Hromic <hhromic@gmail.com>

1 files changed, 90 insertions, 19 deletions

diff --git a/docs/contributing.md b/docs/contributing.md
index 94dbf49..7d18400 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -2,37 +2,108 @@
 
 ## Mailing list
 
-The main communication tool we use is a mailing list:
+The main communication tool in use is the Yocto Project mailing list:
+
 * <yocto@yoctoproject.org>
 * <https://lists.yoctoproject.org/listinfo/yocto>
 
-Feel free to ask any kind of questions but always prepend your email subject
-with "[meta-raspberrypi]". This is because we use the 'yocto' mailing list and
-not a perticular 'meta-raspberrypi' mailing list.
+Feel free to ask any kind of questions but please always prepend your email
+subject with `[meta-raspberrypi]` as this is the global *Yocto* mailing
+list and not a dedicated *meta-raspberrypi* mailing list.
+
+## Formatting patches
+
+First and foremost, all of the contributions to the layer must be compliant
+with the standard openembedded patch guidelines:
+
+* <http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines>
+
+In summary, your commit log messages should be formatted as follows:
+
+    <layer-component>: <short log/statement of what needed to be changed>
+
+    (Optional pointers to external resources, such as defect tracking)
+
+    The intent of your change.
+
+    (Optional: if it's not clear from above, how your change resolves
+    the issues in the first part)
+
+    Signed-off-by: Your Name <yourname@youremail.com>
+
+The `<layer-component>` is the layer component name that your changes affect.
+It is important that you choose it correctly. A simple guide for selecting a
+a good component name is the following:
+
+* For changes that affect *layer recipes*, please just use the **base names**
+  of the affected recipes, separated by commas (`,`), as the component name.
+  For example: use `omxplayer` instead of `omxplayer_git.bb`. If you are
+  adding new recipe(s), just use the new recipe(s) base name(s). An example
+  for changes to multiple recipes would be `userland,vc-graphics,wayland`.
+* For changes that affect the *layer documentation*, please just use `docs`
+  as the component name.
+* For changes that affect *other files*, i.e. under the `conf` directory,
+  please use the full path as the component name, e.g. `conf/layer.conf`.
+* For changes that affect the *layer itself* and do not fall into any of
+  the above cases, please use `meta-raspberrypi` as the component name.
+
+A full example of a suitable commit log message is below:
 
-## Patches and pull requests
+    foobar: Adjusted the foo setting in bar
 
-All the contributions should be compliant with the openembedded patch
-guidelines: <http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines>
+    When using foobar on systems with less than a gigabyte of RAM common
+    usage patterns often result in an Out-of-memory condition causing
+    slowdowns and unexpected application termination.
 
-To contribute to this project you should send pull requests to the github mirror
-(<https://github.com/agherzan/meta-raspberrypi>). **Additionally** you can send
-the patches for review to the above specified mailing list.
+    Low-memory systems should continue to function without running into
+    memory-starvation conditions with minimal cost to systems with more
+    available memory.  High-memory systems will be less able to use the
+    full extent of the system, a dynamically tunable option may be best,
+    long-term.
 
-When creating patches for the mailing list, please use something like:
+    The foo setting in bar was decreased from X to X-50% in order to
+    ensure we don't exhaust all system memory with foobar threads.
+
+    Signed-off-by: Joe Developer <joe.developer@example.com>
+
+A common issue during patch reviewing is commit log formatting, please review
+the above formatting guidelines carefully before sending your patches.
+
+## Sending patches
+
+The preferred method to contribute to this project is to send pull
+requests to the GitHub mirror of the layer:
+
+* <https://github.com/agherzan/meta-raspberrypi>
+
+**In addition**, you may send patches for review to the above specified
+mailing list. In this case, when creating patches using `git` please make
+sure to use the following formatting for the message subject:
 
     git format-patch -s --subject-prefix='meta-raspberrypi][PATCH' origin
 
-When sending patches to the mailing list, please use something like:
+Then, for sending patches to the mailing list, you may use this command:
 
     git send-email --to yocto@yoctoproject.org <generated patch>
 
-## Github issues
+## GitHub issues
+
+In order to manage and track the layer issues more efficiently, the
+GitHub issues facility is used by this project:
+
+* <https://github.com/agherzan/meta-raspberrypi/issues>
+
+If you submit patches that have a GitHub issue associated, please make sure to
+use standard GitHub keywords, e.g. `closes`, `resolves` or `fixes`, before the
+"Signed-off-by" tag to close the relevant issues automatically:
+
+    foobar: Adjusted the foo setting in bar
+
+    Fixes: #324
+
+    Signed-off-by: Joe Developer <joe.developer@example.com>
+
+More information on the available GitHub close keywords can be found here:
 
-In order to manage and trace the meta-raspberrypi issues, we use github issues:
-<https://github.com/agherzan/meta-raspberrypi/issues>
+* <https://help.github.com/articles/closing-issues-using-keywords>
 
-If you push patches which have a github issue associated, please provide the
-issue number in the commit log just before "Signed-off-by" line(s). Example line
-for a bug:
-`[Issue #13]`