Contribution Guidelines

Pacu Contributions

Used Pacu and found something that could be improved? You're in luck! Contributions to Pacu are greatly appreciated.

Pacu is still in its early stages, and bug reports are essential to improving the project. Please submit it via Pacu's issue tracker.

If you'd like to help make Pacu itself better than ever by submitting a pull request, read on.

Making pull requests

• Pull requests should be targeted at the master branch.
• Run linting and tests.
  • make lint test
• Use a descriptive title.
  • If the PR isn't ready to merge prefix the title with [WIP].
• Write a description, and reference related issues in the description, as applicable.
• Respond to comments on pull requests, don't fire and forget.

Dev Workflow

If you want to make a PR go ahead and branch off master. While we do have other branches that are sometimes used, we'd rather keep this simple for now. So this will look something like the following.

git clone https://github.com/RhinoSecurityLabs/pacu.git
git checkout -b feature/my-feature
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt && pip install -r requirements-dev.txt
<any necessary changes>

Then run linting/tests, make sure they pass before you commit. Docker isn't necessary here, it (hopefully) will make your life easier though.

make lint test  # Coverage is limited to Pacu core for now.
flake8 ./path/to/module  # If changes updated a specific module.
git commit -a

After changes are committed you can fork pacu in GitHub, add the new remote to your local git (shown below), and push to your forked repo.

git remote add me https://github.com/<Your User Name>/pacu.git
git push --set-upstream me

If you browse to our pacu repo you should see a banner at the top asking if you want to open a PR for the recently pushed branch.

Feel free to open a PR even if you're not finished, doing so will help us provide early feedback and suggestions to the PR. If you do this just make sure to prefix the PR name with [WIP].

A Note on Testing

Generally, we don't run unit/functional tests on individual modules, while this would be a welcome addition we are more interested in improving Pacu core coverage at the moment. If you make any changes here (non-module code, see next paragraph for modules) we prefer testing be added for the changed code, even if the code wasn't covered before. However don't let this stop you from opening a PR, we're happy to help with this if it's a blocker.

For module's we rely on manual testing, which can be tedious but necessary for now. If you make any changes to PR's please try to test all use cases for that module.

At some point we will likely look into mocking the AWS API for better module testing, one good option here is moto. If this is something you're interested in adding support for with a given module give us a quick ping on the Pacu slack channel or GitHub issue so we can follow along with the progress there.

Style

In the past code style was a bit neglected, we hope to improve this going forward. To help with this please consider the following.

• Python code in Pacu should generally follow Python's style conventions, favoring readability and maintainability.
  • flake8, a Python syntax and style linter is a development dependency for Pacu, and its notifications should mostly be resolved before code contributions are accepted. Use good judgment (or even a code formatter, if you like!) when making code style decisions.
  • Currently, make lint does not enforce checking on modules. We may make this stricter over time, but for now, for code outside Pacu core, we prefer linting be checked manually when possible. You can use flake8 ./path/to/module to run these checks.
• Use descriptive commit messages. Shorter is usually, but not always, better. Consider the 50/72 rule when writing commit messages.
• Pacu code should always use the BSD 3-clause license.

Submitting bug reports

• Report vulnerabilities in Pacu directly to us via the Rhino Security Labs Discord.
• If you have a feature request, an idea, or a bug to report, please submit them here. Please include a description sufficient to reproduce the bug you found, including tracebacks and reproduction steps, and check for other reports of your bug before filing a new bug report. Don't submit duplicates.