Coding style and quality

Code

  • Basically, we want all python code to follow the PEP 8 standard. There are a few exceptions where we see things differently or just aren’t that strict. The setup.cfg file in the project’s source folder contains definitions that allow flake8 to check for violations automatically. See Code checks and unit tests for more information. Use four spaces for indentation.

  • We sort our imports by a certain schema, but you don’t have to do this by hand. Again, setup.cfg contains some definitions that allow the command isort <directory> to automatically sort the imports in your source files.

  • For templates and models, please take a look at the Django Coding Style. We like Django’s class-based views and kindly ask you to use them where appropriate.

  • Please remember to always mark all strings ever displayed to any user for translation.

  • We expect all new code to come with proper tests. When writing new tests, please write them using pytest-style test functions and raw assert statements. Use fixtures to prevent repetitive code. Some old parts of pretix’ test suite are in the style of Python’s unit test module. If you extend those files, you might continue in this style, but please use pytest style for any new test files.

Commits and Pull Requests

Most commits should start as pull requests, therefore this applies to the titles of pull requests as well since the pull request title will become the commit message on merge. We prefer merging with GitHub’s “Squash and merge” feature if the PR contains multiple commits that do not carry value to keep. If there is value in keeping the individual commits, we use “Rebase and merge” instead. Merge commits should be avoided.

  • The commit message should start with a single subject line and can optionally be followed by a commit message body.

    • The subject line should be the shortest possible representation of what the commit changes. Someone who reviewed the commit should able to immediately remember the commit in a couple of weeks based on the subject line and tell it apart from other commits.

    • If there’s additional useful information that we should keep, such as reasoning behind the commit, you can add a longer body, separated from the first line by a blank line.

    • The body should explain what you changed and more importantly why you changed it. There’s no need to iterate how you changed something.

  • The subject line should be capitalized (“Add new feature” instead of “add new feature”) and should not end with a period (“Add new feature” instead of “Add new feature.”)

  • The subject line should be written in imperative mood, as if you were giving a command what the computer should do if the commit is applied. This is how generated commit messages by git itself are already written (“Merge branch …”, “Revert …”) and makes for short and consistent messages.

    • Good: “Fix typo in template”

    • Good: “Add Chinese translation”

    • Good: “Remove deprecated method”

    • Good: “Bump version to 4.4.0”

    • Bad: “Fixed bug with …”

    • Bad: “Fixes bug with …”

    • Bad: “Fixing bug …”

  • If all changes in your commit are in context of a single feature or e.g. a bundled plugin, it makes sense to prefix the subject line with the name of that feature. Examples:

    • “API: Add support for PATCH on customers”

    • “Docs: Add chapter on alpaca feeding”

    • “Stripe: Fix duplicate payments”

    • “Order change form: Fix incorrect validation”

  • If your commit references a GitHub issue that is fully resolved by your commit, start your subject line with the issue ID in the form of “Fix #1234 – Crash in order list”. In this case, you can omit the verb “Fix” at the beginning of the second part of the message to avoid repetition of the word “fix”. If your commit only partially resolves the issue, use “Refs #1234 – Crash in order list” instead.

  • Applies to pretix employees only: If your commit references a sentry issue, please put it in parentheses at the end of the subject line or inside the body (“Fix crash in order list (PRETIXEU-ABC)”). If your commit references a support ticket, please put it in parentheses at the end of the subject line with a “Z#” prefix (“Fix crash in order list (Z#12345)”).

  • If your PR was open for a while and might cause conflicts on merge, please prefer rebasing it (git rebase -i master) over merging master into your branch unless it is prohibitively complicated.