rewrite of contribution guidelines

CONTRIBUTING.md

@@ -1,58 +1,119 @@
 # CONTRIBUTING GUIDELINES
 
-1. [Use the search Luke](#use-the-search-luke)
+Oh-My-Zsh is a community-driven project. Contribution is welcome, encouraged and appreciated.
-2. [You have a problem](#you-have-a-problem)
+It is also essential for the development of the project.
-3. [You have a solution](#you-have-a-solution)
 
-**BONUS:** [You have spare time to volunteer](#you-have-spare-time-to-volunteer)
+These guidelines are an attempt at better addressing the brobdingnagian amount of pending
+issues and pull requests. Please read them closely.
 
+Foremost, be so kind as to [search](#use-the-search-luke), thus ensuring any contribution
+you would make is not already covered.
 
-## USE THE SEARCH LUKE
+* [Issues](#reporting-issues)
+  * [You have a problem](#you-have-a-problem)
+  * [You have a suggestion](#you-have-a-suggestion)
+* [Pull Requests](#submitting-pull-requests)
+  * [Getting started](#getting-started)
+  * [You have a solution](#you-have-a-solution)
+  * [You have an addition](#you-have-an-addition)
+* [Information sources (_aka_ search)](#use-the-search-luke)
 
-> May the Force (of past experiences) be with you.
+**BONUS:** [Volunteering](#you-have-spare-time-to-volunteer)
 
-Trust me, that works 90% of the time.
+## Reporting Issues
 
-You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ)
+### You have a problem
-to be sure it hasn't already come up.
 
-If all fails, your thing hasn't probably been reported yet, so you can go ahead
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
-and read on to the next section.
+your problem.
 
-
+If you find one, comment on it so we can know there are more people experiencing it.
-## YOU HAVE A PROBLEM
-
-See [point 1](#use-the-search-luke).
-
-If the problem is already reported, comment on the issue so we can know there's
-more people with the problem.
 
 If not, look at the [Troubleshooting](https://github.com/robbyrussell/oh-my-zsh/wiki/Troubleshooting)
 page for instructions on how to gather data to better debug your problem.
 
-Then, you can go ahead and submit an issue with as much detail as you can provide.
+Then, you can go ahead and create an issue with as much detail as you can provide.
-We'll do our very best to help you.
+It should include the data gathered as indicated above, along with:
 
-*TODO: fill later*
+1. How to reproduce the problem
+2. What the correct behavior should be
+3. What the actual behavior is
 
+Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle
+(starting with `@`) in your message.
 
-## YOU HAVE A SOLUTION
+We will do our very best to help you.
 
-See [point 1](#use-the-search-luke).
+### You have a suggestion
+
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
+your suggestion.
+
+If you find one, comment on it so we can know there are more people supporting it.
+
+If not, you can go ahead and create an issue. Please copy to anyone relevant (_eg_ plugin
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
+
+## Submitting Pull Requests
+
+### Getting started
+
+You should be familiar with the basics of
+[contributing on GitHub](https://help.github.com/articles/using-pull-requests) and have a fork
+[properly set up](https://github.com/robbyrussell/oh-my-zsh/wiki/Contribution-Technical-Practices).
+
+You MUST always create PRs with _a dedicated branch_ based on the latest upstream tree.
+
+If you create your own PR, please make sure you do it right. Also be so kind as to reference
+any issue that would be solved in the PR description body,
+[for instance](https://help.github.com/articles/closing-issues-via-commit-messages/)
+_"Fixes #XXXX"_ for issue number XXXX.
+
+### You have a solution
+
+Please be so kind as to [search](#use-the-search-luke) for any open issue already covering
+your [problem](#you-have-a-problem), and any pending PR covering your solution.
 
 If the solution is already reported, try it out and +1 the pull request if the
 solution works ok. On the other hand, if you think your solution is better, post
 it so we can have both solutions to compare.
 
-If not, then go ahead and submit a PR.
+If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin
-**Unless your solution is yet another [theme](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now).**
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
 
-*TODO: fill later*
+### You have an addition
 
+Please [do not](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now)
+send themes for now.
+
+Please be so kind as to [search](#use-the-search-luke) for any pending PR covering or
+related to what you want to add.
+
+If you find one, try it out and work with the author on a common solution.
+
+If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin
+maintainers) by mentioning their GitHub handle (starting with `@`) in your message.
 
 ----
 
-### YOU HAVE SPARE TIME TO VOLUNTEER
+## Use the Search, Luke
+
+> May the Force (of past experiences) be with you
+
+GitHub offers [many search features](https://help.github.com/articles/searching-github/)
+to help you check whether a similar contribution to yours already exists. Please search
+before making any contribution, it avoids duplicates and eases maintenance. Trust me,
+that works 90% of the time.
+
+You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ)
+to be sure your contribution has not already come up.
+
+If all fails, your thing has probably not been reported yet, so you can go ahead
+and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests).
+
+----
+
+### You have spare time to volunteer
 
 Very nice!! :)