Toot contribution guide
=======================

Firstly, thank you for contributing to toot!

Relevant links which will be referenced below:

* [toot documentation](https://toot.bezdomni.net/)
* [toot-discuss mailing list](https://lists.sr.ht/~ihabunek/toot-discuss)
  used for discussion as well as accepting patches
* [toot project on github](https://github.com/ihabunek/toot)
  here you can report issues and submit pull requests
* #toot IRC channel on [libera.chat](https://libera.chat)

## Code of conduct

Please be kind and patient. Toot is maintained by one human with a full time
job.

## I have a question

First, check if your question is addressed in the documentation or the mailing
list. If not, feel free to send an email to the mailing list. You may want to
subscribe to the mailing list to receive replies.

Alternatively, you can ask your question on the IRC channel and ping me
(ihabunek). You may have to wait for a response, please be patient.

Please don't open Github issues for questions.

## I want to contribute

### Reporting a bug

First check you're using the
[latest version](https://github.com/ihabunek/toot/releases/) of toot and verify
the bug is present in this version.

Search [Github issues](https://github.com/ihabunek/toot/issues) to check the bug
hasn't already been reported.

To report a bug open an
[issue on Github](https://github.com/ihabunek/toot/issues) or send an
email to the [mailing list](https://lists.sr.ht/~ihabunek/toot-discuss).

* Run `toot env` and include its contents in the bug report.
* Explain the behavior you would expect and the actual behavior.
* Please provide as much context as possible and describe the reproduction steps
  that someone else can follow to recreate the issue on their own.

### Suggesting enhancements

This includes suggesting new features or changes to existing ones.

Search Github issues to check the enhancement has not already been requested. If
it hasn't, [open a new issue](https://github.com/ihabunek/toot/issues).

Your request will be reviewed to see if it's a good fit for toot. Implementing
requested features depends on the available time and energy of the maintainer
and other contributors.

### Contributing code

When contributing to toot, please only submit code that you have authored or
code whose license allows it to be included in toot. You agree that the code
you submit will be published under the [toot license](LICENSE).

#### Setting up a dev environment

Check out toot (or a fork) and install it into a virtual environment.

```bash
git clone git@github.com:ihabunek/toot.git
cd toot
python3 -m venv _env

# On Linux/Mac
source _env/bin/activate

# On Windows
_env\bin\activate.bat

pip install --editable ".[dev,test]"
```

While the virtual env is active, running `toot` will execute the one you checked
out. This allows you to make changes and test them.

#### Crafting good commits

Please put some effort into breaking your contribution up into a series of well
formed commits. If you're unsure what this means, there is a good guide
available at [https://cbea.ms/git-commit/](https://cbea.ms/git-commit/).

Rules for commits:

* each commit should ideally contain only one change
* don't bundle multiple unrelated changes into a single commit
* write descriptive and well formatted commit messages

Rules for commit messages:

* separate subject from body with a blank line
* limit the subject line to 50 characters
* capitalize the subject line
* do not end the subject line with a period
* use the imperative mood in the subject line
* wrap the body at 72 characters
* use the body to explain what and why vs. how

For a more detailed explanation with examples see the guide at
[https://cbea.ms/git-commit/](https://cbea.ms/git-commit/)

If you use vim to write your commit messages, it will already enforce some of
these rules for you.

#### Run tests before submitting

You can run code and style tests by running:

```
make test
```

This runs three tools:

* `pytest` runs the test suite
* `flake8` checks code formatting
* `vermin` checks that minimum python version

Please ensure all three commands succeed before submitting your patches.

#### Submitting patches

To submit your code either open
[a pull request](https://github.com/ihabunek/toot/pulls) on Github, or send
patch(es) to [the mailing list](https://lists.sr.ht/~ihabunek/toot-discuss).

If sending to the mailing list, patches should be sent using `git send-email`.
If you're unsure how to do this, there is a good guide at
[https://git-send-email.io/](https://git-send-email.io/).

---

Parts of this guide were taken from the following sources:

* [https://contributing.md/](https://contributing.md/)
* [https://cbea.ms/git-commit/](https://cbea.ms/git-commit/)