From 2e063a9c440070b6e85b178f74f705bb8c7ea70c Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 6 Jul 2022 15:32:50 +0200 Subject: [PATCH] docs: using black for code formatting --- docs/development.rst | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index 5051829d..506bf725 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -119,14 +119,29 @@ Code is stored on GitHub, in the `Borgbackup organization `_ should be sent there as well. See also the :ref:`support` section for more details. -Style guide ------------ +Style guide / Automated Code Formatting +--------------------------------------- -We generally follow `pep8 -`_, with 120 columns -instead of 79. We do *not* use form-feed (``^L``) characters to -separate sections either. Compliance is tested automatically when -you run the tests. +We use `black`_ for automatically formatting the code. + +If you work on the code, it is recommended that you run black **before each commit** +(so that new code is always using the desired formatting and no additional commits +are required to fix the formatting). + +:: + + pip install -r requirements.d/codestyle.txt # everybody use same black version + black --check . # only check, don't change + black . # reformat the code + + +The CI workflows will check the code formatting and will fail if it is not formatted correctly. + +When (mass-)reformatting existing code, we need to avoid ruining `git blame`, so please +follow their `guide about avoiding ruining git blame`_: + +.. _black: https://black.readthedocs.io/ +.. _guide about avoiding ruining git blame: https://black.readthedocs.io/en/stable/guides/introducing_black_to_your_project.html#avoiding-ruining-git-blame Continuous Integration ----------------------