2014-04-18 15:01:54 +00:00
# Hello, World!
2012-11-07 02:18:58 +00:00
2014-03-03 20:39:40 +00:00
Thanks for your interest in making Metasploit -- and therefore, the
2014-04-18 15:01:54 +00:00
world -- a better place!
Are you about to report a bug? If so, please use our [Redmine Bug
Tracker](https://dev.metasploit.com/redmine/projects/framework). An
account is required but it only takes a minute or two.
Are you about to report a security vulnerability in Metasploit?
If so, please take a look at Rapid's [Vulnerability
Disclosure Policy](https://www.rapid7.com/disclosure.jsp) policy.
Are you about to contribute some new functionality, a bug fix, or a new
Metasploit module? If so, read on...
# Contributing to Metasploit
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.
2014-02-24 17:57:38 +00:00
2014-03-03 20:39:40 +00:00
If you care not to follow these rules, your contribution **will** be
closed (*Road House* style). Sorry!
2014-02-24 17:57:38 +00:00
2014-04-18 15:01:54 +00:00
This is intended to be a **short** list. The
2014-03-03 20:39:40 +00:00
[wiki ](https://github.com/rapid7/metasploit-framework/wiki ) is much more
2014-03-04 20:06:34 +00:00
exhaustive and reveals many mysteries. If you read nothing else, take a
look at the standard [development environment setup
guide](https://github.com/rapid7/metasploit-framework/wiki/Setting-Up-a-Metasploit-Development-Environment)
and Metasploit's [Common Coding Mistakes ](https://github.com/rapid7/metasploit-framework/wiki/Common-Metasploit-Module-Coding-Mistakes ).
2014-02-24 17:57:38 +00:00
## Code Contributions
2014-03-04 08:42:13 +00:00
* **Do** stick to the [Ruby style guide ](https://github.com/bbatsov/ruby-style-guide ).
2014-03-04 18:46:42 +00:00
* **Do** follow the [50/72 rule ](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html ) for Git commit messages.
2014-03-04 19:05:50 +00:00
* **Do** create a [topic branch ](http://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches ) to work on instead of working directly on `master` .
2014-02-24 17:57:38 +00:00
### Pull Requests
2014-04-06 03:21:44 +00:00
* **Do** target your pull request to the **master branch** . Not staging, not develop, not release.
2014-03-04 18:44:12 +00:00
* **Do** specify a descriptive title to make searching for your pull request easier.
2014-03-03 20:39:40 +00:00
* **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.
2014-02-24 17:57:38 +00:00
2014-03-04 18:19:34 +00:00
Pull requests [#2940 ](https://github.com/rapid7/metasploit-framework/pull/2940 ) and [#3043 ](https://github.com/rapid7/metasploit-framework/pull/3043 ) are a couple good examples to follow.
2014-03-04 08:38:47 +00:00
2014-02-24 17:57:38 +00:00
#### New Modules
2014-03-03 20:39:40 +00:00
* **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 ).
2014-06-02 20:37:20 +00:00
* **Do** use the [many module mixin APIs ](https://dev.metasploit.com/api/ ). Wheel improvements are welcome; wheel reinventions, not so much.
2014-03-03 20:39:40 +00:00
* **Don't** include more than one module per pull request.
2014-02-24 17:57:38 +00:00
#### Library Code
2014-03-03 20:39:40 +00:00
* **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.
2014-04-06 03:21:44 +00:00
* **Don't** fix a lot of things in one pull request. Small fixes are easier to validate.
2014-02-24 17:57:38 +00:00
#### Bug Fixes
2014-03-03 20:39:40 +00:00
* **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.
2014-02-24 17:57:38 +00:00
## Bug Reports
2014-04-18 15:01:54 +00:00
* **Do** report vulnerabilities in Rapid7 software directly to security@rapid7.com.
* **Do** create a Redmine account and report your non-vulnerability bugs there.
2014-03-04 19:16:55 +00:00
* **Do** write a detailed description of your bug and use a descriptive title.
2014-03-03 20:39:40 +00:00
* **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.
2014-03-04 18:22:14 +00:00
Redmine issues [#8762 ](https://dev.metasploit.com/redmine/issues/8762 ) and [#8764 ](https://dev.metasploit.com/redmine/issues/8764 ) are a couple good examples to follow.
2014-03-04 18:19:34 +00:00
2014-03-03 20:39:40 +00:00
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.
2014-02-24 17:57:38 +00:00
2014-03-03 20:39:40 +00:00
Also, **thank you** for taking the few moments to read this far! You're
already way ahead of the curve, so keep it up!
