miaowware/qrm2
1
0
Fork 0
mirror of https://github.com/miaowware/qrm2.git synced 2025-07-29 11:32:25 -04:00
Code Issues Actions Projects Releases Wiki Activity

Create developer guidelines

Browse Source
This commit is contained in:
classabbyamp 2020-10-02 01:39:19 -04:00 committed by GitHub
parent 7e35e8949a
commit 2d10f4e15a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
CONTRIBUTING.md
View File

@ -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/

46
DEVELOPING.md Normal file
View File

@ -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