diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 2888487..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: Bug report -about: Report a bug to help us improve qrm -title: '' -labels: bug -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Run command '...' with input '...' -2. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**System (include if related to running the bot):** - - OS: [e.g. Linux, Docker] - - Version: [e.g. 22] - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index abd211f..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for qrm -title: '' -labels: enhancement -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md deleted file mode 100644 index 47e9bf8..0000000 --- a/.github/pull_request_template.md +++ /dev/null @@ -1,29 +0,0 @@ -### 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 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..e3d824c --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,54 @@ +# Development Guide for qrm + +**Make sure to also read [`CONTRIBUTING.md`][0], 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). + +These instructions are fairly \*NIX-centric, so if you would like to develop on Windows, it is suggested that the Windows Subsystem for Linux be used. + +## While You Develop + +To run qrm, use the command `./run.sh`. +We recommend you use the `--pass-errors` flag 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. + +Make sure to add [type hints][4] to your code. +This is what `mypy` validates in the code. + +Using `dev-notes` for documentation is especially important if you introduce a new json file format (like for maps and bandplans) 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. +You can also enable them for this project in your IDE if supported. +This will give you automatic and continuous linting and type checking. + +### 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, +but we prefer that developers check this before committing and opening PRs. + +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, +- etc. + +[0]: https://github.com/miaowware/.github/blob/master/CONTRIBUTING.md +[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://docs.python.org/3/library/typing.html \ No newline at end of file