Various and sundry text updates to CONTRIBUTING.md

Namely, all sentences should end with periods. Other light changes.
Please cover the rest of my comments mentioned on commit 30fec1af (or
argue with them) then PR away!
bug/bundler_fix
Tod Beardsley 2014-03-03 14:39:40 -06:00
parent 30fec1af01
commit defdf05f6d
No known key found for this signature in database
GPG Key ID: 1EFFB682ADB9F193
1 changed files with 36 additions and 25 deletions

View File

@ -1,48 +1,59 @@
# Contributing to Metasploit
The following is a list of rules for contributing to Metasploit.
Thanks for your interest in making Metasploit -- and therefore, the
world -- a better place! What you see here in CONTRIBUTING.md is a
bullet-point list of the do's and don'ts of how to make sure *your*
valuable contributions actually make it into Metasploit's master branch.
If you cannot follow these rules, your pull request or bug report **will** be closed (*Road House* style).
If you care not to follow these rules, your contribution **will** be
closed (*Road House* style). Sorry!
First of all, read the [wiki](https://github.com/rapid7/metasploit-framework/wiki). You don't have to read all of it, but you should read the parts that are relevant to you.
If you don't know where to start, you should read the [development environment setup guide](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment).
Incidentally, this is a **short** list. The
[wiki](https://github.com/rapid7/metasploit-framework/wiki) is much more
exhaustive and reveals many mysteries. If you don't know where to start,
you should take a look at the standard [development environment setup
guide](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment).
## Code Contributions
* **Do** follow the [Ruby style guide](https://github.com/bbatsov/ruby-style-guide)
* **Do** follow the [HACKING](HACKING) guide
* **Do** stick to the [Ruby style guide](https://github.com/bbatsov/ruby-style-guide)
### Pull Requests
* **Do** include [console output](https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks) - example runs are useful
* **Do** include [verification steps](https://help.github.com/articles/writing-on-github#task-lists) - this greatly helps with testing
* **Do not** leave your pull request description blank
* **Do not** abandon your pull request - being responsive helps us land your code faster
* **Do** include [console output](https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks), especially for witnessable effects in `msfconsole`.
* **Do** list [verification steps](https://help.github.com/articles/writing-on-github#task-lists) so your code is testable.
* **Don't** leave your pull request description blank.
* **Don't** abandon your pull request. Being responsive helps us land your code faster.
#### New Modules
* **Do** run `tools/msftidy.rb` against your module and fix any errors or warnings that come up
* **Do** use the [API](https://dev.metasploit.com/documents/api/) - don't reinvent the wheel (you can improve it, though)
* **Do not** include more than one module per pull request
* **Do** run `tools/msftidy.rb` against your module and fix any errors or warnings that come up. Even better would be to set up `msftidy.rb` as a [pre-commit hook](https://github.com/rapid7/metasploit-framework/blob/master/tools/dev/pre-commit-hook.rb).
* **Do** use the [API](https://dev.metasploit.com/documents/api/). Wheel improvements are welcome; wheel reinventions, not so much.
* **Don't** include more than one module per pull request.
#### Library Code
* **Do** write [RSpec](http://rspec.info/) tests - even the smallest change in library land can thoroughly screw things up
* **Do** follow [Better Specs](http://betterspecs.org/) - it's like the style guide for specs
* **Do** write [YARD](http://yardoc.org/) documentation - this makes it easier for people to use your code
* **Do** write [RSpec](http://rspec.info/) tests - even the smallest change in library land can thoroughly screw things up.
* **Do** follow [Better Specs](http://betterspecs.org/) - it's like the style guide for specs.
* **Do** write [YARD](http://yardoc.org/) documentation - this makes it easier for people to use your code.
#### Bug Fixes
* **Do** include reproduction steps in the form of verification steps
* **Do** include a link to the corresponding [Redmine](https://dev.metasploit.com/redmine/projects/framework) issue, if any
* **Do** include reproduction steps in the form of verification steps.
* **Do** include a link to the corresponding [Redmine](https://dev.metasploit.com/redmine/projects/framework) issue in the format of `SeeRM #1234` in your commit description.
## Bug Reports
* **Do** create a Redmine account and report your bug there
* **Do** write a detailed description of your bug
* **Do** include reproduction steps, stack traces, and anything else that might help us verify and fix your bug
* **Do not** file duplicate reports - search for your bug before filing a new report
* **Do not** report a bug on GitHub - we don't track bugs on GitHub
* **Do** create a Redmine account and report your bug there.
* **Do** write a detailed description of your bug.
* **Do** include reproduction steps, stack traces, and anything else that might help us verify and fix your bug.
* **Don't** file duplicate reports - search for your bug before filing a new report.
* **Don't** report a bug on GitHub. Use [Redmine](https://dev.metasploit.com/redmine/projects/framework) instead.
If you need help, talk to us on IRC at **#metasploit on freenode** or e-mail us at msvdev@metasploit.com.
If you need some more guidance, talk to the main body of open
source contributors over on the [Freenode IRC channel](http://webchat.freenode.net/?channels=%23metasploit&uio=d4)
or e-mail us at [metasploit-hackers](https://lists.sourceforge.net/lists/listinfo/metasploit-hackers)
mailing list.
Also, **thank you** for taking the few moments to read this far! You're
already way ahead of the curve, so keep it up!