114 lines
6.3 KiB
Markdown
114 lines
6.3 KiB
Markdown
# Git
|
|
|
|
## Workflow rules
|
|
1. Coding on Gwendolyn is performed in [feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). This means all code should be added in a separate feature branch before it's added to the `master` branch.
|
|
1. Feature branches must be created from current `master` branch when
|
|
1. Never push to the `master` branch. All code from feature branches should be added with pull requests. [NikolajDanger](https://github.com/NikolajDanger) is the only developer who can accept pull requests to `master`.
|
|
1. ***All code*** pushed to `master` must:
|
|
+ Work
|
|
+ Be reachable when the bot is running
|
|
+ Follow the code style guidelines laid out later in this doc.
|
|
1. Code pushed to feature branches require none of those.
|
|
|
|
## Commit messages
|
|
Commit subject lines should not be longer than 72 characters. Each line in the body must not be longer than 80 characters.
|
|
|
|
Whether a commit requires more than a subject line is up to the developer's discretion. Another developer should be able to know _exactly_ what has changed by reading the commit.
|
|
|
|
### Emoji
|
|
Commit messages must start with an emoji relating to the nature of the commit, because emojis are fun. Emojis are put in commit messages with github shortcodes (e.g. :heart: is `:heart:`). [Emojipedia](https://emojipedia.org/) has the github shortcodes for all emoji.
|
|
|
|
There are no rules for which emoji to use where, but here's some inspiration:
|
|
|
|
:bug: (`:bug:`) - Fixing a bug.
|
|
|
|
:pencil: (`:pencil:`) - Adding to or changing `README.md`, documentation, logging code or other text.
|
|
|
|
:stop_sign: (`:stop_sign:`) - Adding or changing code that deals with exceptions and errors.
|
|
|
|
:sparkles: (`:sparkles:`) - Adding new feature.
|
|
|
|
# Terminology
|
|
Comments, strings, variable names, class names, docstrings, as well as all other text in your code, filenames and directory names should use this terminology correctly.
|
|
|
|
**bot** - The current discord client and instance of the Gwendolyn class.
|
|
|
|
**cog** - A class that contains an amount of bot commands.
|
|
|
|
**ctx** - The [context](https://discordpy.readthedocs.io/en/latest/ext/commands/api.html#context) of a command. All command and error functions should use `ctx` as the context variable.
|
|
|
|
**utils** - Functions, classes and methods that are only used by the bot and don't use the Discord API.
|
|
|
|
# Code
|
|
|
|
## Code Style
|
|
All the Python code should follow the [PEP 8 guidelines](https://www.python.org/dev/peps/pep-0008/), with the following additions:
|
|
+ Variable and function names must fully consist of either full words or common/understandable abbreviations.
|
|
+ Use f-strings when applicable.
|
|
|
|
### Documentation
|
|
+ Comment lines should not exede 72 characters.
|
|
+ There should be a comment for each import, explaining where the module is used.
|
|
+ Comments should explain things that are not obvious and not described in a docstring.
|
|
|
|
### Docstrings
|
|
+ There should be a docstring defining every module, function, class and method for all Python code in Gwendolyn.
|
|
+ Obvious cases can be described in a single-line docstring, `"""Like this"""`.
|
|
+ Single-line docstrings should have the start- and end-quotations be on the same line. Multi-line docstrings should have the end-quotation on its own line:
|
|
```
|
|
"""Like this
|
|
|
|
Some docstring
|
|
"""
|
|
```
|
|
+ Class docstrings should define and describe all class attributes, and provide a list of class methods, showing input and output types. This information should be provided like this:
|
|
```
|
|
"""Class docstring
|
|
|
|
*Attributes*
|
|
------------
|
|
color : string
|
|
The color of the class.
|
|
dead : bool
|
|
Whether the class is dead or not.
|
|
|
|
*Methods*
|
|
---------
|
|
changeColor(newColor : str) -> bool
|
|
kill() -> bool
|
|
"""
|
|
```
|
|
+ Method and function docstrings should define and describe all parameters and what it returns, in the same format as the docstring above.
|
|
+ Module docstrings should define classes and functions in the module, in the same format as the docstring above.
|
|
|
|
## Error Handling
|
|
Code called by a command should not have `try` and `except` statements. All errors should be raised to the `on_command_error()` or `Command.error()` functions, where they can be dealt with.
|
|
|
|
## Cogs
|
|
The `Command` methods in cogs should only exist to perform small tasks or call code from elsewhere in the Gwendolyn code. Therefore, a single `Command` method should not contain more than 3 lines of code and should not use any modules other than `Discord.py` and the Gwendolyn modules. If a cog method calls a function in Gwendolyn, ctx must be passed, and the function should handle sending messages.
|
|
|
|
## Codebase Management
|
|
### Folders
|
|
+ `cogs/` contains the command cogs.
|
|
+ `funcs/` contains all functions and classes called on to perform commands. All functions must be accessible through a class, of which the `Gwendolyn` class has an instance as an attribute.
|
|
+ `gwendolyn/resources/` contains the images, lookup databases, fonts etc. that the rest of the code uses.
|
|
|
|
### Important files
|
|
+ `Gwendolyn.py` contains the Gwendolyn class and running it starts the bot. It should be lightweight and not more than 100 lines.
|
|
|
|
## Logging
|
|
Things you should know about the logging:
|
|
+ `log()` is a method of the `Gwendolyn` class.
|
|
+ It is used to log to the log-file (`gwendolyn.log`) and print to the command line.
|
|
+ The function can take either a list of strings or a string as its first parameter. If the parameter is a string, it is converted to a list of 1 string.
|
|
+ The first string in the list is printed. All strings in the list are logged to the log-file.
|
|
+ If the list is longer than 1 string, `(details in log)` is added to the printed string.
|
|
+ The level parameter is 20 by default, which means the level is `INFO`. 40 corresponds to a level of `ERROR`, and 25 corresponds to `print`.
|
|
+ Logs of level `INFO` are not printed.
|
|
+ Logs of level `ERROR` should only be created in the `on_command_error()`, `on_error()` or `Command.error()` functions.
|
|
|
|
### Logging rules
|
|
1. Never call the `log_this()` function from `/utils/utilFuncs/`. Always call `bot.log`.
|
|
1. The `on_slash_command()` and `on_ready()` events are the only times log should be called at level 25. `INFO` level logs should be used for all other logging.
|
|
1. Always provide the channel id if available. Although you shouldn't pass the channel id to a function purely to use it in logs.
|