Update CONTRIBUTING.md

Improve the text stylistically and grammatically. Rewrite intro to nudge
people into the right direction and warn them about the usual fate of
spontaneous PRs.

CONTRIBUTING.md

@@ -1,48 +1,48 @@
 # Contribution Guidelines
 
-PEG.js is an open source project and it welcomes contributions. To make sure
+The best way to contribute to PEG.js is by using it and giving back useful
-your contributions are useful and the overall process is smooth, please adhere
+feedback — reporting discovered bugs or requesting missing features.
-to these guidelines.
 
-You can contribute in three main ways: by reporting bugs, requesting features,
+You can also contribute code, but be advised that many patches end up being
-and contributing code.
+rejected, usually because the change doesn’t fit the project or because of
+various implementation issues. In almost all cases it’s best to get in touch
+first before sending a patch.
 
 ## Reporting Bugs
 
-You can report bugs using [GitHub issues][issues]. Before submitting a bug
+Report bugs using [GitHub issues][issues]. Before submitting a bug report,
-report, [search the existing reports][issues-search-bugs] to see if the bug
+please [search existing reports][issues-search-bugs] to see if the bug wasn’t
-wasn’t reported already.
+reported already.
 
-Each bug report should contain this information:
+In the report, please describe:
 
-  * Steps to reproduce
+  * Steps to reproduce the problem
-  * What you expected to happen
+  * Expected result(s)
-  * What happened instead
+  * Actual result(s)
 
-In most cases, it is useful to include a **minimal** example (grammar + input)
+In most cases, it’s also useful to include a **minimal** example (grammar +
-reproducing the problem.
+input) reproducing the problem.
 
 ## Requesting Features
 
-You can request features using [GitHub issues][issues]. Before submitting a
+Request features using [GitHub issues][issues]. Before submitting a feature
-feature request, [search the existing requests][issues-search-enhancements] to
+request, please [search existing requests][issues-search-enhancements] to see if
-see if the feature wasn’t requested already.
+the feature wasn’t requested already.
 
-Each feature request should contain this information:
+In the request, please describe:
 
-  * Feature description
+  * How the feature should work
-  * Why do you request it
+  * Use case(s) behind it
 
 ## Contributing Code
 
-You can contribute code using [GitHub pull requests][pulls]. However, for
+Contribute code using [GitHub pull requests][pulls]. For non-trivial changes,
-anything but trivial changes, file an issue first. Your idea may not fit the
+first file a corresponding bug report or feature request. This will ensure the
-project, or the implementation you have in mind may not be the right one. Filing
+*problem* is separated from a *solution*.
-an issue in these cases will prevent wasting time and effort on both sides.
 
-Split your change into atomic commits with descriptive commit messages adhering
+Split your change into atomic commits with descriptive messages adhering to
-to [these conventions][git-commit-messages]. Have a look in the commit history
+[these conventions][git-commit-messages]. Have a look in the commit history to
-to see good examples.
+see good examples.
 
 When appropriate, add documentation and tests.