Skip to content

How to Contribute

Mrigank Anand edited this page Aug 8, 2021 · 10 revisions

First off, thanks for taking the time to contribute! We gladly support and appreciate anyone is interested to contribute to the OWASP Honeypot Project. Overall developers may focus on developing core framework or modules. Please consider that we are using PEP8 python code style and using Codacy to figure the code quality. In addition, GitHub Actions will test your PR automatically on several Python versions (3.x). Before sending your PR, make sure you have added code-based documentation to your codes. If you use any code/library/module with a license, add the license into external license file.

We love your input! We want to make contributing to this project as easy and transparent as possible.

Finding an issue

We make extensive use of issue labels to designate the status of various issues. We have a standard set of labels across all projects, documented here. Here are some of the ones that are most relevant to finding a good issue to work on:

  • Issues tagged help wanted or good first issue or enhancement are available for community contribution : These issues are available for community contribution, and you do not need an approval to work on one of these. You may work on an issue labeled good first issue even if it's not your first issue. Check the issue comments/labels to see whether someone else has indicated that they are working on it. If someone is already working on it and there has been activity within the last 7 days, you may want to find a different issue to work on.
  • Issues without any of the above labels may be open for contribution. Please add a comment to ask whether the issue is available before starting work.

Some helpful saved searches on GitHub than can assist with finding an issue:

Contribution process

  • Once you've found an issue you'd like to work on, please follow these steps to make your contribution: Comment on it and say you're working on that issue. This is to avoid conflicts with others also working on the issue.

  • Write your code and submit your pull request. Be sure to read and follow our pull request guidelines!

  • Wait for code review and address any issues raised as soon as you can.

A note on collaboration: We encourage people to collaborate as much as possible. We especially appreciate contributors reviewing each other's pull requests, as long as you are kind and constructive when you do so.

Proposing a new issue

If you want to work on something that there is no GitHub issue for, follow these steps:

  • Create a new GitHub issue associated with the relevant repository and propose your change there. Be sure to include implementation details, and the rationale for the proposed change.
  • We are very reluctant to accept random pull requests without a related issue created first. Wait for a project maintainer to evaluate your issue and decide whether it's something that we will accept a pull request for.
  • Once the project maintainer has approved the issue, you may start work on code as described in the "Contribution process" section above

Pull Request Guidelines

1. Fork it 🍴

You can get your own fork/copy of OWASP-Honeypot by using the Fork button.

Fork Button

2. Clone it 👥

You need to clone (download) it to local machine using

git clone https://github.com/Your_Username/OWASP-Honeypot.git

This makes a local copy of repository in your machine.

Once you have cloned the OWASP-Honeypot repository in GitHub, move to that folder first using change directory command.

# This will change directory to a folder OWASP-Honeypot
cd OWASP-Honeypot

Move to this folder for all other commands.

3. Set it up ⬆️

Run the following commands to see that your local copy has a reference to your forked remote repository in GitHub : octocat:

git remote -v
origin  https://github.com/Your_Username/OWASP-Honeypot.git (fetch)
origin  https://github.com/Your_Username/OWASP-Honeypot.git (push)

Now, add a reference to the original OWASP-Honeypot repository using

git remote add upstream https://github.com/zdresearch/OWASP-Honeypot.git

This adds a new remote named upstream.

See the changes using

git remote -v
origin    https://github.com/Your_Username/OWASP-Honeypot.git (fetch)
origin    https://github.com/Your_Username/OWASP-Honeypot.git (push)
upstream  https://github.com/zdresearch/OWASP-Honeypot.git    (fetch)
upstream  https://github.com/zdresearch/OWASP-Honeypot.git    (push)

4. Sync it

Always keep your local copy of repository updated with the original repository. Before making any changes and/or in an appropriate interval, run the following commands carefully to update your local repository.

# Fetch all remote repositories and delete any deleted remote branches
git fetch --all --prune

# Switch to `master` branch
git checkout master

# Reset local `master` branch to match `upstream` repository's `master` branch
git reset --hard upstream/master

# Push changes to your forked `Plant_Disease_Detection` repo
git push origin master

5. Ready Steady Go...

Once you have completed these steps, you are ready to start contributing by checking our Help Wanted Issues and creating pull requests.

6. Create a new branch ‼️

Whenever you are going to make contribution. Please create separate branch using the following command and keep your master branch clean (i.e. synced with remote branch).

# It will create a new branch with name Branch_Name and will switch to that branch.
git checkout -b Branch_Name

Create a separate branch for every contribution and try to use the same name of the branch as of folder.

To switch to desired branch

# To switch from one folder to other
git checkout Branch_Name

Now make your changes in this branch.

If your changes required addition of functions/ API endpoints/ features that are not being tested in the unit tests, then add corresponding tests to it in the tests directory.

7. Local Testing

Once you are finished implementing your changes, test your changes locally using the following commands:

# Run Modules Test
python3 ohp.py -m all --test

The above command will take some time, so be patient. When it ends, ensure that no errors were printed on the terminal.

# Run API
python3 ohp.py --start-api-server
# Run Unit tests on a separate terminal
python3 -m pytest -rPp

Ensure that all the units tests passed before creating a pull request.

8. Push a commit

To add the changes to the branch use:

# To add all files to branch Branch_Name
git add .

Type in a message explaining the changes in brief using:

# This message gets associated with all files you have changed
git commit -m 'relevant message'

Now, Push your awesome work to your remote repository using

# To push your work to your remote repository
git push -u origin Branch_Name

9. Create a Pull Request

Finally, go to your repository in browser and click on compare and pull requests and select the compare across forks option.

Compare across Forks

Change the base fork branch to development branch.

Pull Request Base

Add a title and description to your pull request that explains your precious effort.

Sit and relax till we review your PR, you've made your contribution to our project.

Code guidelines

  • Write comprehensive and robust tests that cover the changes you've made in your work.
  • Follow the appropriate code style standards for the language and framework you're using (e.g. PEP 8 for Python).
  • Write readable code – keep functions small and modular and name variables descriptively.
  • Document your code thoroughly.
  • Make sure all the existing tests pass.

We aim to review pull requests as soon as possible.