diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0d6eb3e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Contributing + +If you have an idea for a new feature or just want to help out with a bug +fix, please refer to this guide and follow the rules before submitting a +pull request. + +## Submitting Issues + +If you aren't a programmer or don't have the time to contribute code to the +project, we would still appreciate bug reports and feature requests. Please +use the appropriate issue type in the GitHub issue system to report either +bugs or feature requests. + +When reporting bugs, ensure you include the current version pwncat you have +installed, what type of target/victim you are using, what payload you used +on the target to gain a shell, any relevant tracebacks, and of course +screenshots if they add context to your problem. In general, the more +information we have, the more chance there is we can fix the problem. + +For feature requests, please be very specific on what you would like pwncat +to do. We can't read your mind, and English isn't perfect. If you are +interested in or willing to help implement your new feature, please explicitly +let us know. This will help in prioritizing the issue. + +## Versioning + +pwncat follows Semantic Versioning. You can learn about the basics of semver +[here](https://semver.org). pwncat does not currently have any release +schedule, but in general the following rules apply: + +- `PATCH` fixes are released whenever there is either significant aggregate of + bug fixes or when a significantly agregious bug is fixed. The decision for + what "significant" means will be decided by a project owner. +- `MINOR` releases are for added functionality. The pwncat API is relatively + stable, but still has not attained `v1.0.0` status, and therefore minor + releases could make breaking API changes. However, a concerted effort + should be made to make all changes backwards compatible. + +As mentioned above, pwncat has not reached `v1.0.0` yet. As such, I don't have +rules yet for `MAJOR` version bumps. I will update this file as the situation +develops. + +## Making Changes + +In general, when contributing to a project on GitHub, you should work from a +branch. This helps organize your changes within the project. There are two +main branches which pwncat uses to organize contributions: `master` and the +next release branch (named like `release-vX.Y.Z`). + +- Any bug fixes which do not add new features should be made targeting `master`. +- Any new features should be made targeting the latest `release-vX.Y.Z`. + +When forking the repository to make contributions, you can work directly out +of your fork's `master` or `release` branches or fork them. When creating a +pull request, you must target the appropriate branch based on the intent of +your work. + +Pull requests targeting the wrong branch will be retargeted, which could +cause issues while merging. + +## Styling and Format + +The majority of pwncat is written in Python. We use `python-black` to format +code in a consistent and readable manner. We recommend you install a Black +plugin for your editor or IDE to ensure all code is formatted prior to +opening a pull request. + +Beyond Black, you should also run `isort` and `flake8` within your branch +prior to opening a pull request. `isort` will sort your imports to ensure +they are easy to read. `flake8` will notify you of some common Python +errors. pwncat has `flake8` and `isort` configurations, so the process is +as simple as running the associated tool. + +Prior to creating a pull request, please run the following from the repository +root to ensure formatting is in order: + +```sh +# Automatically fixes imports +isort ./pwncat +# Automatically fixes formatting +black ./pwncat +# Warns of errors or other syntax problems +flake8 +``` + +## Testing Your Changes + +Testing pwncat is difficult. There are some unit tests implemented in `tests/`. +These tests can be executed with `pytest`, but you must provide suitable targets +for the testing framework. The `run-tests.sh` script uses `podman` to start two +containers to act as targets, and then runs all tests. One container is a Ubuntu +machine with a bind shell and the other is a CentOS container with a bind shell. + +If you are creating Windows features, you can run the Windows tests as well by +manually providing a Windows bind shell target: + +```sh +WINDOWS_HOST=10.10.10.10 WINDOWS_BIND_PORT=4444 ./run-tests.sh +``` + +The included unit tests are not great. They do not have a lot of coverage, but +they at least ensure that the basic automated functionality of pwncat is not +broken across some common target types.