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.
redux
David Majda 8 years ago
parent b10ddc4877
commit 6eb42ddae7

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

Loading…
Cancel
Save