metasploit-framework/CONTRIBUTING.md

4.1 KiB

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 care not to follow these rules, your contribution will be closed (Road House style). Sorry!

Incidentally, this is a short list. The wiki is much more exhaustive and reveals many mysteries. If you read nothing else, take a look at the standard development environment setup guide and Metasploit's Common Coding Mistakes.

Code Contributions

Pull Requests

  • Do specify a descriptive title to make searching for your pull request easier.
  • Do include console output, especially for witnessable effects in msfconsole.
  • Do list verification steps 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.

Pull requests #2940 and #3043 are a couple good examples to follow.

New Modules

  • 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.
  • Do use the 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 tests - even the smallest change in library land can thoroughly screw things up.
  • Do follow Better Specs - it's like the style guide for specs.
  • Do write YARD 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 issue in the format of SeeRM #1234 in your commit description.

Bug Reports

  • Do report vulnerabilities in Rapid7 software to security@rapid7.com.
  • Do create a Redmine account and report your bug there.
  • Do write a detailed description of your bug and use a descriptive title.
  • 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 instead.

Redmine issues #8762 and #8764 are a couple good examples to follow.

If you need some more guidance, talk to the main body of open source contributors over on the Freenode IRC channel or e-mail us at 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!