|
| 1 | +# Contributing |
| 2 | + |
| 3 | +[](https://github.com/OWASP/wrongsecrets-ctf-party/graphs/contributors) |
| 4 | + |
| 5 | + |
| 6 | +This document describes how you can contribute to WrongSecrets CTF Party. Please read it carefully. |
| 7 | + |
| 8 | +**Table of Contents** |
| 9 | + |
| 10 | +- [How to Contribute to the Project](#how-to-contribute-to-the-project) |
| 11 | +- [How to set up your Contributor Environment](#how-to-set-up-your-contributor-environment) |
| 12 | +- [How to get your PR Accepted](#how-to-get-your-pr-accepted) |
| 13 | + |
| 14 | +## How to Contribute to the project |
| 15 | + |
| 16 | +There are a couple of ways on how you can contribute to the project: |
| 17 | + |
| 18 | +- **File [issues](https://github.com/OWASP/wrongsecrets-ctf-party/issues "WrongSecrets CTF Party Issues")** for missing content or errors. Explain what you think is missing and give a suggestion as to where it could be added. |
| 19 | +- **Create a [pull request (PR)](https://github.com/OWASP/wrongsecrets-ctf-party/pulls "Create a pull request")**. This is a direct contribution to the project and may be merged after review. You should ideally [create an issue](https://github.com/OWASP/wrongsecrets-ctf-party/issues "WrongSecrets CTF Party Issues") for any PR you would like to submit, as we can first review the merit of the PR and avoid any unnecessary work. This is of course not needed for small modifications such as correcting typos. |
| 20 | +- **Promote us by giving us a Star or share information via social media**. |
| 21 | + |
| 22 | +## How to get your PR accepted |
| 23 | + |
| 24 | +Your PR is valuable to us, and to make sure we can integrate it smoothly, we have a few items for you to consider. In short: |
| 25 | +The minimum requirements for code contributions are: |
| 26 | + |
| 27 | +1. The code _must_ be compliant with the configured pre-commit hooks. |
| 28 | +2. All new and changed code _should_ have a corresponding unit and/or integration test. |
| 29 | +3. New and changed lessons _must_ have a corresponding integration test. |
| 30 | +4. [Status checks](https://docs.github.com/en/github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) should pass for your last commit. |
| 31 | + |
| 32 | +Additionally, the following guidelines can help: |
| 33 | + |
| 34 | +### Keep your pull requests limited to a single issue |
| 35 | + |
| 36 | +Pull requests should be as small/atomic as possible. Large, wide-sweeping changes in a pull request will be **rejected**, with comments to isolate the specific code in your pull request. Some examples: |
| 37 | + |
| 38 | +- If you are making spelling corrections in the docs, don't modify other files. |
| 39 | +- If you are adding new functions don't '_cleanup_' unrelated functions. That cleanup belongs in another pull request. |
| 40 | + |
| 41 | +### Write a good commit message |
| 42 | + |
| 43 | +- Make sure your commit message passes the [conventional commit standards](https://www.conventionalcommits.org/en/v1.0.0/) |
| 44 | +- Explain why you make the changes. [More info about a good commit message.](https://betterprogramming.pub/stop-writing-bad-commit-messages-8df79517177d) |
| 45 | +- If you fix an issue with your commit, please close the issue by [adding one of the keywords and the issue number](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) to your commit message. |
| 46 | + |
| 47 | + For example: `Fix #545` or `Closes #10` |
| 48 | + |
| 49 | +## How to set up your Contributor Environment |
| 50 | + |
| 51 | +1. Create a GitHub account. Multiple different GitHub subscription plans are available, but you only need a free one. Follow [these steps](https://help.github.com/en/articles/signing-up-for-a-new-github-account "Signing up for a new GitHub account") to set up your account. |
| 52 | +2. Fork the repository. Creating a fork means creating a copy of the repository on your own account, which you can modify without any impact on this repository. GitHub has an [article that describes all the needed steps](https://help.github.com/en/articles/fork-a-repo "Fork a repo"). |
| 53 | +3. Clone your own repository to your host computer so that you can make modifications. If you followed the GitHub tutorial from step 2, you have already done this. |
| 54 | +4. Go to the newly cloned directory "wrongsecrets" and add the remote upstream repository: |
| 55 | + |
| 56 | + ```bash |
| 57 | + $ git remote -v |
| 58 | + origin [email protected]: <your Github handle >/wrongsecrets-ctf-party.git (fetch) |
| 59 | + origin [email protected]: <your Github handle >/wrongsecrets-ctf-party.git (push) |
| 60 | + |
| 61 | + $ git remote add upstream [email protected]:OWASP/wrongsecrets-ctf-party.git |
| 62 | + |
| 63 | + $ git remote -v |
| 64 | + origin [email protected]: <your Github handle >/wrongsecrets-ctf-party.git (fetch) |
| 65 | + origin [email protected]: <your Github handle >/wrongsecrets-ctf-party.git (push) |
| 66 | + upstream [email protected]:OWASP/wrongsecrets-ctf-party.git (fetch) |
| 67 | + upstream [email protected]:OWASP/wrongsecrets-ctf-party.git (push) |
| 68 | + ``` |
| 69 | + |
| 70 | + See also the GitHub documentation on "[Configuring a remote for a fork](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork "Configuring a remote for a fork")". |
| 71 | + |
| 72 | +5. Choose what to work on, based on any of the outstanding [issues](https://github.com/OWASP/wrongsecrets-ctf-party/issues "WrongSecrets CTF Party Issues"). |
| 73 | +6. Create a branch so that you can cleanly work on the chosen issue: `git checkout -b fix/Issue66` |
| 74 | +7. Open your favorite editor and start making modifications. We recommend using the [IntelliJ Idea](https://www.jetbrains.com/idea/). |
| 75 | +8. Install [pre-commit](https://pre-commit.com/#install) the dependencies for our pre-commit configuration to make sure your code complies with standards used in the project. This requires terraform, [terraform-docs](https://github.com/terraform-docs/terraform-docs#installation), [tflint](https://github.com/terraform-linters/tflint#installation), and [commitlint](https://commitlint.js.org/#/guides-local-setup). For commitlint, you need [NodeJS](https://nodejs.org/en/download/) installed, after which you you can use `npm install` in the root folder of this project. |
| 76 | +9. Install the pre-commit hook using `pre-commit install --hook-type commit-msg`. We recommend to run `pre-commit run -a` every so often if you're working on a bigger change. |
| 77 | +10. After your modifications are done, push them to your forked repository. This can be done by executing the command `git add MYFILE` for every file you have modified, followed by `git commit -m 'your commit message here'` to commit the modifications and `git push` to push your modifications to GitHub. |
| 78 | +11. Create a Pull Request (PR) by going to your fork, <https://github.com/Your_Github_Handle/wrongsecrets> and click on the "New Pull Request" button. The target branch should typically be the main branch. When submitting a PR, be sure to follow the checklist that is provided in the PR template. The checklist itself will be filled out by the reviewer. |
| 79 | +12. If something in your git workflow went wrong (and e.g., the precommit hook CI run failed), check out ["O Shit, Git!?!"](https://ohshitgit.com/) to view tips on editing your historical commit message(s), among others. |
| 80 | +13. Your PR will be reviewed and comments may be given. In order to process a comment, simply make modifications to the same branch as before and push them to your repository. GitHub will automatically detect these changes and add them to your existing PR. |
| 81 | +14. When starting on a new PR in the future, make sure to always keep your local repo up to date: |
| 82 | + |
| 83 | + ```bash |
| 84 | + git fetch upstream |
| 85 | + git merge upstream/develop |
| 86 | + ``` |
| 87 | + |
| 88 | + See also the following article for further explanation on "[How to Keep a Downstream git Repository Current with Upstream Repository Changes](https://medium.com/sweetmeat/how-to-keep-a-downstream-git-repository-current-with-upstream-repository-changes-10b76fad6d97 "How to Keep a Downstream git Repository Current with Upstream Repository Changes")". |
| 89 | + |
| 90 | +If at any time you want to work on a different issue, you can simply switch to a different branch, as explained in step 5. |
| 91 | + |
| 92 | +> Tip: Don't try to work on too many issues at once though, as it will be a lot more difficult to merge branches the longer they are open. |
| 93 | +
|
| 94 | +## What not to do |
| 95 | +
|
| 96 | +Although we greatly appreciate any and all contributions to the project, there are a few things that you should take into consideration: |
| 97 | +
|
| 98 | +- The Wrongsecrets project should not be used as a platform for advertisement for commercial tools, companies or individuals. Write-ups should be written with free and open-source tools in mind and commercial tools are typically not accepted, unless as a reference in the security tools section. |
| 99 | +- Unnecessary self-promotion of tools or blog posts is frowned upon. If you have a relation with on of the URLs or tools you are referencing, please state so in the PR so that we can verify that the reference is in line with the rest of the guide. |
| 100 | +
|
| 101 | +Please be sure to take a careful look at our [Code of Conduct](https://github.com/OWASP/wrongsecrets-ctf-party/blob/main/CODE_OF_CONDUCT.md) for all the details. |
0 commit comments