# 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.