diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcbc76e..ffcfc1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,143 @@ # Contributing -Contributions are always welcome, no matter how large or small. Before -contributing, please read the -[code of conduct](CODE_OF_CONDUCT.md). +Contributions are always welcome, no matter how large or small. Here are the guidelines we ask our contributors to follow: -## Running Tests + - [Code of Conduct](#coc) + - [Issues and Bugs](#issue) + - [Feature Requests](#feature) + - [Submission Guidelines](#submit) + - [Coding Rules](#rules) + - [Running Test Suite](#tests) + +## Code of Conduct +We want to keep our project open and inclusive. We ask that before you +contribute, you read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). + +## Found an Issue? +We definitely want to hear from you! + +If you find a bug in the source code or a mistake in the docs, you can help us by +submitting an issue to our [Repository][issues]. Make sure you search through our existing [open and closed issues][issues-archive] in order to avoid duplicate submissions. + +Want to contribute with a fix? Even better! Just submit a [Pull Request][pulls]. + +**Please read the [Submission Guidelines](#submit) below**. + +## Want a Feature? +Need a new feature no yet available on node-mocks-http? Submit a new feature to our [GitHub Repository][issues]. + +Think you can help us out by implementing the feature yourself? Go for it! Just craft and submit your [Pull Request][pulls]. + +**Please read the [Submission Guidelines](#submit) below**. + +## Submission Guidelines + +### Submitting an Issue +Before you submit your issue search the [archive][archive], maybe your question was already answered. Let's avoid duplicates. + +If you believe your issue is a bug, and you can't find a issue in the [archive][issues-archive], just open a new issue. + +**Help us help you!** + +Provide the following information to help us identify and fix the issue in a timely manner: + +* **Overview** - describe the issue the best way you can, and if possible include a stack trace +* **Use Case** - explain why you consider this a bug +* **Version(s)** - tell us what version of node-mocks-http you're currently using +* **Reproduce** - it would be awesome if you could provide a live example (using [Plunker][plunker] or + [JSFiddle][jsfiddle]), or at least a step-by-step description on how to reproduce it +* **Suggestions** - if you have identified the lines of code or the commit responsible for the problem please include it as well + +### Submitting a Pull Request +We are a *Pull Request-friendly* project! + +Your pull requests are always welcome. We only ask that you adhere to the following guidelines before you submit your pull request: + +* Search [GitHub][pulls] for an open or closed Pull Request that may be similar to yours. Avoid duplicates! +* Fork our [repo][repo] and create a local clone, if you haven't done so already. + + ```shell + git clone https://github.com/YOUR-NAME/node-mocks-http.git + ``` + +* If you had previously cloned the [repo][repo], make sure you sync it with the upstream repository. + + ```shell + git remote add upstream https://github.com/howardabrams/node-mocks-http.git + git fetch upstream + git checkout master + git merge upstream/master + ``` + +* Create a new topic branch: + + ```shell + git checkout -b my-awesome-fix master + ``` + +* Now do your thing! Create your fix/patch, **including appropriate test cases**. +* Follow our [Coding Rules](#rules). +* Run our test suite, as described in [below](#tests), + and ensure that all tests pass. +* Commit your changes using a descriptive commit message + + ```shell + git commit -a + ``` + + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. + +* Push your branch to GitHub: + + ```shell + git push origin my-awesome-fix + ``` + +* In GitHub, send a pull request to `node-mocks-http`. +* If we find any issues we may suggest that you: + * Make the required updates. + * Re-run the [test suite](#tests) to ensure tests are still passing. + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase master -i + git push origin my-awesome-fix -f + ``` + +That's it! + +#### Post merged cleanup + +After we merge your pull request, you can safely delete your branch and pull the changes from our main (upstream) repository: + +* Delete the remote branch on GitHub either through the GitHub web interface or your local shell as follows: + + ```shell + git push origin --delete my-awesome-fix + ``` + +* Check out the master branch: + + ```shell + git checkout master -f + ``` + +* Delete the local branch: + + ```shell + git branch -D my-awesome-fix + ``` + +* Update your master with the latest upstream version: + + ```shell + git pull --ff upstream master + ``` + +## Coding Rules +*Coming soon! Please stay tuned!* + +## Running Test Suite Install `jshint` globally. @@ -20,3 +153,11 @@ Then simply run the tests. ```bash ./run-tests ``` + +[repo]: https://github.com/howardabrams/node-mocks-http +[issues]: https://github.com/howardabrams/node-mocks-http/issues +[issues-archive]: https://github.com/howardabrams/node-mocks-http/issues?q=is%3Aissue +[pulls]: https://github.com/howardabrams/node-mocks-http/pulls +[pulls-archive]: https://github.com/howardabrams/node-mocks-http/pulls?q=is%3Apr +[jsfiddle]: http://jsfiddle.net/ +[plunker]: http://plnkr.co/edit