Coding Guidelines - PKlempe/SAM GitHub Wiki

General Rules

  • Codestyle conforms to PEP-8 Official Python Style Guide.
  • Methods that are a part of a module API or any other type of contract, or just methods that have a high complexity, will be documented using docstrings and ideally type annotations.
  • Code should always be checked by linters (Pylint, MyPy) to find errors early.
  • Commits have to be reviewed by at least one other contributer before merging and a merge will only be feasible if all existing tests pass. (Assuming any tests have been written).
  • There will be a dedicated file for global application configuration, where all configuration will be in.
  • "Pythonic" design patterns will be used to the best of our knowledge.
  • Defined APIs (also internal, e.g. the public methods of module) will not be changed, only extended, except if absolutely neccessary and with the okay of the whole development team.

In the development process all developers and their opinion are to be respected equally, irrespective of their position, general experience and relation or position in this project. The only exception is, if a developer can prove to reasonable satisfaction that he has a more extensive knowledge regarding the issue.

Branches, Commits & Pull requests

We should make sure that the names of branches begin with the type of improvement followed by a hashtag with the corresponding issue number and divided by a regular slash. For Commits and Pull Requests, only the second part with the issue number is relevant.

Recommended Structure for branches: {feature, bugfix, enhancement} / #00-descriptive-text

Examples (Branch):

feature/#3-added-text-to-speech-support

bugfix/#11-fix-error-where-bot-becomes-skynet

enhancement/#25-update-discord.py-version

Examples (Commits, Pull Requests):

#8: Implement some stuff

#26: Fix the one special bug

After each push or creation of a Pull Request three checks are run:

  1. pylint on all non-test-files
  2. mypy on all files
  3. pytest on all tests

If one of these checks fails, meaning any test fails or pylint/mypy finds an error, then the Pull Request is prevented until the cause has been eliminated.