pwncat/CONTRIBUTING.md

# 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.

## Submitting Pull Requests

When submitting a pull request, ensure you have read through and comply with
these contributing rules. The pull request template should guide you through
the things that need done before merging code.

For help with running pre-merge tools, see the styling and formatting section
below. For running pytest test cases, see the testing section.

Before submitting your changes in a pull request, please add a brief one-line
summary to the `CHANGELOG.md` file under the `[Unreleased]` heading. This makes
releases more straightforward and bug fixes and features are added along the way.
For information on the format of the changelog, see
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

If you are submitting a bug fix, annotate this with `Fixes #XXX` replacing the
`XXX` with the issue number. This ensures that the issue will be closed once
the bug fix is merged. If your bug fix does not **completely** fix the issue,
do not use the `Fixes` keyword. Instead, mention the issue by number in your
pull request to ensure the link between the issue and pull request is clear.

## 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.