|
1 |
| -# Contributing to BeEF |
| 1 | +# Contributing |
| 2 | +### Anyone is welcome to make BeEF better! |
| 3 | +Thank you for wanting to contribute to BeEF. It's effort like yours that helps make BeEF such a great tool. |
2 | 4 |
|
3 |
| -Anyone is welcome to make BeEF better! |
| 5 | +Following these guidelines shows that you respect the time of the developers developing this open source project and helps them help you. In response to this, they should return that respect in addressing your issue, assisting with changes, and helping you finalize your pull requests. |
4 | 6 |
|
5 |
| -Below are the steps needed to add code to BeEF on Github to the master branch: |
| 7 | +### We want any form of helpful contributions! |
6 | 8 |
|
7 |
| -1. Fork the repository and create a new branch |
8 | 9 |
|
9 |
| -2. Write and commit your new code to that branch |
| 10 | +BeEF is an open source project and we love to receive contributions from the community! There are many ways to contribute, from writing tutorials or blog posts, improving or translating the documentation, answering questions on the project, submitting bug reports and feature requests or writing or reviewing code which can be merged into BeEF itself. |
10 | 11 |
|
11 |
| -3. Run the existing tests to make sure they pass |
| 12 | +# Ground Rules |
12 | 13 |
|
13 |
| -4. Make a pull request from the forked branch to BeEF master |
| 14 | +### Responsibilities |
| 15 | +> * When making an issue, ensure the issue template is filled out, failure to do so can and will result in a closed ticket and a delay in support. |
| 16 | +> * We now have a two-week of unresponsiveness period before closing a ticket, if this happens, just comment responding to the issue which will re-open the ticket. Ensure to make sure all information requested is provided. |
| 17 | +> * Ensure cross-platform compatibility for every change that's accepted. Mac and Linux are currently supported. |
| 18 | +> * Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get community feedback. |
| 19 | +> * Ensure language is as respectful and appropriate as possible. |
| 20 | +> * Keep merges as straightforward as possible, only address one issue per commit where possible. |
| 21 | +> * Be welcoming to newcomers and try to assist where possible, everyone needs help. |
14 | 22 |
|
15 |
| -See https://github.com/beefproject/beef/wiki/BeEF-Testing for steps to write tests. |
| 23 | +# Where to start |
| 24 | +### Looking to make your first contribution |
16 | 25 |
|
17 |
| -TL;DR: |
18 |
| -``` |
19 |
| -bundle install --with test |
20 |
| -bundle exec rake spec |
21 |
| -``` |
| 26 | + Unsure where to begin contributing to BeEF? You can start by looking through these issues: |
22 | 27 |
|
23 |
| -4. Write tests in RSpec for your new code (module, extension etc.) |
| 28 | + * Good First Issue - issues which should only require a few changes, and are good to start with. |
| 29 | + * Question - issues which are a question and need a response. A good way to learn more about BeEF is to try to solve a problem. |
24 | 30 |
|
25 |
| -5. Run all tests again to make sure they all pass |
| 31 | +At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first. |
26 | 32 |
|
27 |
| -6. Edit existing wiki page / add a new one explaining the new features, including: |
| 33 | +If a maintainer asks you to "rebase" your PR, they're saying that code has changed, and that you need to update your branch so it's easier to merge. |
| 34 | + |
| 35 | +### Ruby best practise |
| 36 | +Do read through: https://rubystyle.guide |
| 37 | +Try and follow through with the practices throughout, even going through it once will help keep the codebase consistent. |
| 38 | +Use Rubocop to help ensure that the changes adhere to current standards, we are currently catching up old codebase to match. |
| 39 | +Just run the following in the /beef directory. |
| 40 | +> rubocop |
| 41 | +
|
| 42 | +# Getting started |
| 43 | + |
| 44 | +### How to submit a contribution. |
| 45 | + |
| 46 | +1. Create your own fork of the code |
| 47 | + |
| 48 | +2. Checkout the master branch |
| 49 | +> git checkout master |
| 50 | +
|
| 51 | +3. Create a new branch for your feature |
| 52 | +> git checkout -b my-cool-new-feature |
| 53 | +
|
| 54 | +4. Add your new files |
| 55 | +> git add modules/my-cool-new-module |
| 56 | +
|
| 57 | +5. Modify or write a test case/s in Rspec for your changes |
| 58 | + |
| 59 | +6. Commit your changes with a relevant message |
| 60 | +> git commit |
| 61 | +
|
| 62 | +7. Push your changes to GitHub |
| 63 | +> git push origin my-cool-new-feature |
| 64 | +
|
| 65 | +8. Run all tests again to make sure they all pass |
| 66 | + |
| 67 | +9. Edit existing wiki page / add a new one explaining the new features, including: |
28 | 68 | - sample usage (command snippets, steps and/or screenshots)
|
29 | 69 | - internal working (code snippets & explanation)
|
30 | 70 |
|
31 |
| -7. Submit a Pull Request, explaining: |
32 |
| - - what you have added |
33 |
| - - where to find help about it (link to wiki page) |
| 71 | +10. Now browse to the following URL and create your pull request from your fork to beef master |
| 72 | + - Fill out the Pull Request Template |
| 73 | + - https://github.com/beefproject/beef/pulls |
| 74 | + |
| 75 | + |
| 76 | +# How to report a bug |
| 77 | +If you find a security vulnerability, do NOT open an issue. Email security@beefproject.com instead. |
| 78 | + |
| 79 | +When the security team receives a security bug email, they will assign it to a primary handler. |
| 80 | +This person will coordinate the fix and release process, involving the following steps: |
34 | 81 |
|
35 |
| -If you're brand new to contributing to open-source projects, check out Githubs guide: |
36 |
| -https://github.com/firstcontributions/first-contributions/blob/master/README.md |
| 82 | +* Confirm the problem and find the affected versions. |
| 83 | +* Audit code to find any potential similar problems. |
| 84 | +* Prepare fixes |
0 commit comments