From c969848e7a5592458f11165c782f8365a78dd69d Mon Sep 17 00:00:00 2001 From: Ivan Habunek Date: Sat, 31 Dec 2022 11:40:11 +0100 Subject: [PATCH] Add a contribution guide --- CONTRIBUTING.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f0ec0ff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,135 @@ +Toot contribution guide +======================= + +Firstly, thank you for contributing to toot! + +Relevant links which will be referenced below: + +* [toot documentation](https://toot.readthedocs.io/) +* [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 governed 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 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. Be patient. + +### 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. + +``` +git clone git@github.com:ihabunek/toot.git +cd toot +python3 -m venv _env +source _env/bin/activate +pip install --editable . +pip install -r requirements-dev.txt +pip install -r requirements-test.txt +``` + +While the virtual env is active, running `toot` will execute the one you checked +out. This allows you to make changes and test them. + +Run tests: + +``` +pytest +``` + +Check code style: + +``` +flake8 +``` + +#### 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/. + +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 + +If you use vim to write your commit messages, it will already enforce these +rules for you. + +#### 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/. + +--- + +Parts of this guide were taken from the following sources: + +* https://contributing.md/ +* https://cbea.ms/git-commit/