From 2d10f4e15a49823446fb27df71021f933f6a0ab3 Mon Sep 17 00:00:00 2001 From: classabbyamp <5366828+classabbyamp@users.noreply.github.com> Date: Fri, 2 Oct 2020 01:39:19 -0400 Subject: [PATCH] Create developer guidelines --- CONTRIBUTING.md | 77 ------------------------------------------------- DEVELOPING.md | 46 +++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 77 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 4f6fac3..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 0000000..d95555a --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,46 @@ +# Development Guidelines for qrm + +**Make sure to also read `CONTRIBUTING.md`, everything in there applies here.** + +### Environment Setup + +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. + +Using `dev-notes` for documentation 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 + +In addition to testing functionality, make sure to run `flake8` to ensure your code uses the proper style, and `mypy [files...]` to ensure proper typing. + +### 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. + +[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