diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..47e9bf8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,29 @@ +### Description + +*Describe the changes you made here.* + +Fixes #{issue} + +### Type of change + +Please delete options that are not relevant. + +- Bug fix (non-breaking change which fixes an issue) +- New feature (non-breaking change which adds functionality) +- Breaking change (fix or feature that would cause existing functionality to not work as expected) +- This change requires a documentation update + +### How has this been tested? + +*Describe the procedure used for verifying your changes here.* + +### Checklist + +- [ ] Issue exists for PR +- [ ] Code reviewed by the author +- [ ] Code documented (comments or other documentation) +- [ ] Changes tested +- [ ] `flake8` passes +- [ ] `CHANGELOG.md` updated +- [ ] Informative commit messages +- [ ] Descriptive PR title diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4f6fac3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,77 @@ +# Contributing to qrm + +## Before You Start + +- Make sure there's an issue for the feature, bugfix, or other improvement you want to make. +- Make sure it's something that the project maintainers want. + We can discuss it and assign the issue to you. +- Make sure work isn't already being done on the issue. + +### Environment Setup + +Once all of the above is done, you can get started by setting up your development envronment. + +1. [Fork this repo][1] into your own GitHub namespace. +1. Make sure the `master` branch is up to date, then make yourself a new branch with a descriptive name. +1. Once the forked repo is cloned and on the proper branch, you can set up the development environment. + 1. Install python 3.7 or higher. + 1. Run `make dev-install`. + This should install everything you need to develop and run qrm. + 1. [Create a bot and token][2], and add it to `data/keys.py`. + Also add your [QRZ credentials][3] if needed. + 1. In `data/options.py`, change values as needed. + Some commands require adding your Discord user ID to `owner_uids`. + 1. To activate the virtual env that was created by `make`, run `source botenv/bin/activate` (or the equivelent for your shell or operating system). + +## While You Develop + +To run qrm, use the command `./run.sh`. +We recommend you use the `--pass-errors` flags to avoid perpetual restart loops if you break the bot. +It exists because repeatedly mashing [Ctrl+C] at high speed to break a fast loop is not fun. + +Commit messages should be descriptive and mention issues that they fix ("fixes #123") or contain progress on ("progress on #123"). +Make commits as needed, but try to keep it reasonable. +If there are too many, your contribution may be squashed when merged. +You may want to squash your commits locally yourself: + +```sh +git reset --soft [commit before your changes] +git commit +``` + +Make sure to document your code as you go, in both comments and external documentation (in `/dev-notes/`) as needed. +`dev-notes` is especially important if you introduce a new json file format or to document some development process (like the command to crush the various images in the repository). + +**Test your changes.** +If your code doesn't work, it's not ready for merging. +Make sure you not only test intended behaviour, but also edge cases and error cases. +Make sure to run `flake8` to ensure your code uses the proper style, and `mypy [files...]` to ensure proper typing. + +If you're making a user-facing change, put a quick summary in `CHANGELOG.md` under the `[Unreleased]` heading. +Follow the [Keep a Changelog][4] format. + +### A Note on Style + +qrm tries to keep to PEP 8 style whenever possible. +Use the utility `flake8` to check that you follow this style. +When you start a PR or push commits, GitHub will automatically run this for you; +if that fails, you will be expected to fix those errors before merge. + +Otherwise, try to follow the existing style: +double-quotes except when required to be single, +indentation of mult-line structures matching other examples in the code, +add type hints, +etc. + +## When You're Ready to Merge + +1. When you have finished working on your contribution, create a pull request from your fork's branch into the master branch of this repository. +1. Read through and complete the pull request template. + If the checklist is not complete, your contribution will not be merged. +1. Your pull request will get reviewed by at least one maintainer. +1. If approved, another maintainer may merge the pull request if everything looks good. + +[1]: https://github.com/miaowware/qrm2/fork +[2]: https://discordpy.readthedocs.io/en/latest/discord.html +[3]: https://www.qrz.com/page/xml_data.html +[4]: https://keepachangelog.com/en/1.0.0/ diff --git a/README.md b/README.md index c42ac52..2a849ad 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,10 @@ Run. For more information on options, see the [quick-bot-no-pain run.sh document $ run.sh ``` +## Contributing + +Check out the [contribution guidelines](/CONTRIBUTING.md) for more information about how to contribute to this project. + ## Copyright Copyright (C) 2019-2020 Abigail Gold, 0x5c