From ae047037dcabb6071a77653dd9b414590389bef3 Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Tue, 9 Nov 2021 16:30:32 +0100 Subject: [PATCH] Docs: Add style guide for commit messages (#2281) Co-authored-by: Richard Schreiber --- doc/development/contribution/style.rst | 63 +++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/doc/development/contribution/style.rst b/doc/development/contribution/style.rst index 995bff7708..858d31b180 100644 --- a/doc/development/contribution/style.rst +++ b/doc/development/contribution/style.rst @@ -1,6 +1,11 @@ +.. spelling:: Rebase rebasing + 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 :ref:`checksandtests` @@ -20,8 +25,62 @@ Coding style and quality 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. -* Please keep the first line of your commit messages short. When referencing an issue, please phrase it like - ``Fix #123 -- Problems with order creation`` or ``Refs #123 -- Fix this part of that bug``. +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. .. _PEP 8: https://legacy.python.org/dev/peps/pep-0008/