@ -1,48 +1,48 @@
# Contribution Guidelines
# 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
## Reporting Bugs
You can r eport bugs using [GitHub issues][issues]. Before submitting a bug
R eport 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
## Requesting Features
You can r equest features using [GitHub issues][issues]. Before submitting a
R equest 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
## 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.
When appropriate, add documentation and tests.