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.

Git Flow

master

This branch is sacred, and should always have functional and correct code. If you do find any issues on while testing or reviewing the master branch, please submit an issue.

dev

Code in the dev branch doesn't have to be perfect, but it should be runnable. The dev branch is generally where new features or bugfixes are developed and tested, either as direct commits or within feature branches based off of dev.

Feature Branches

The dividing line between a branch-worthy feature and a direct-to-dev commit is generally a common-sense decision. A substantial feature should have its own branch, where "substantial" means something that involves a lot of code, multiple commits, or a significant amount of testing.

In general, developers are in charge of their own feature branch, and it's inconsiderate to push to another developer's feature branch without talking to them first. Developers self-manage their feature branches and merging is the responsibility of the developer.

Hotfixes

If possible, we want to avoid commits directly to master, but sometimes there will have no choice. Breaking bugs and security vulnerabilities good examples of things that need to be patched ASAP. Applying hotfixes should be done very carefully, and should always be verified as functional before the merge.

A Note on Testing

No matter what branch code is pushed too, developers are responsible for writing runnable code. If a developer is unable to perform the necessary basic testing by themselves, they should ask for help, and follow up with testers to make sure everything is working. Feature branches are an exception. It is perfectly fine to have non-functional commits for others to review or work on, and it's only the pre-merge commit that should be tested.

Contributing Code

• Python code in Pacu should generally follow Python's style conventions, favoring readability and maintainability above all.
  • 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. A .flake8 configuration file is included with Pacu and contains a small number of specific rules that flake8 will ignore during Pacu's early development, but which may or may not eventually be removed. Use good judgment (or even a code formatter, if you like!) when making code style decisions.
• 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.

Making pull requests

• Pull requests should be targeted at the master branch.
• Use a descriptive title.
• Write a description, and reference related issues in the description, as applicable.
• Respond to comments on pull requests, don't fire and forget.

Submitting bug reports

• Report vulnerabilities in Pacu directly to us via email: [email protected].
• 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.