[couchdb] branch main updated: Improve documentation of source code format checks

[va...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

vatamane pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git


The following commit(s) were added to refs/heads/main by this push:
     new 0c49292a8 Improve documentation of source code format checks
0c49292a8 is described below

commit 0c49292a8a2f51a4d6e61edbeec9619ab01c2a5c
Author: Gabor Pali <ga...@ibm.com>
AuthorDate: Thu Mar 9 14:17:07 2023 +0100

    Improve documentation of source code format checks
    
    - Add `python-black-update` for `make help`.
    - In the output of `make help`, diffentiate between Erlang and
      Python source code checks.
    - Include the use of `black` in the developer documentation.
    - Hide `erlfmt` commands for the respective targets.  This makes
      the targets consistent with their Windows versions.
---
 Makefile       | 11 ++++++-----
 Makefile.win   |  7 ++++---
 README-DEV.rst |  7 +++++++
 3 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/Makefile b/Makefile
index 726d38d86..3d9a58787 100644
--- a/Makefile
+++ b/Makefile
@@ -204,19 +204,19 @@ soak-eunit: couch
 	@$(REBAR) setup_eunit 2> /dev/null
 	while [ $$? -eq 0 ] ; do $(REBAR) -r eunit $(EUNIT_OPTS) ; done
 
-# target: erlfmt-check - Check source code formatting
+# target: erlfmt-check - Check Erlang source code formatting
 erlfmt-check:
-	ERLFMT_PATH=$(ERLFMT) python3 dev/format_check.py
+	@ERLFMT_PATH=$(ERLFMT) python3 dev/format_check.py
 
-# target: erlfmt-format - Apply source code format standards automatically
+# target: erlfmt-format - Apply Erlang source code format standards automatically
 erlfmt-format:
-	ERLFMT_PATH=$(ERLFMT) python3 dev/format_all.py
+	@ERLFMT_PATH=$(ERLFMT) python3 dev/format_all.py
 
 .venv/bin/black:
 	@python3 -m venv .venv
 	@.venv/bin/pip3 install black || touch .venv/bin/black
 
-# target: python-black - Python code formatter, runs only on Python >= 3.6
+# target: python-black - Check Python code formatting (requires Python >= 3.6)
 python-black: .venv/bin/black
 	@python3 -c "import sys; exit(1 if sys.version_info < (3,6) else 0)" || \
 	       echo "Python formatter not supported on Python < 3.6; check results on a newer platform"
@@ -225,6 +225,7 @@ python-black: .venv/bin/black
 		--exclude="build/|buck-out/|dist/|_build/|\.git/|\.hg/|\.mypy_cache/|\.nox/|\.tox/|\.venv/|src/erlfmt|src/jiffy|src/rebar/pr2relnotes.py|src/fauxton" \
 		build-aux/*.py dev/run dev/format_*.py src/mango/test/*.py src/docs/src/conf.py src/docs/ext/*.py .
 
+# target: python-black-update - Apply Python source code format standards automatically (requires Python >= 3.6)
 python-black-update: .venv/bin/black
 	@python3 -c "import sys; exit(1 if sys.version_info < (3,6) else 0)" || \
 	       echo "Python formatter not supported on Python < 3.6; check results on a newer platform"
diff --git a/Makefile.win b/Makefile.win
index 458b61d47..c9990c4ff 100644
--- a/Makefile.win
+++ b/Makefile.win
@@ -180,12 +180,12 @@ just-eunit: export ERL_AFLAGS = $(shell echo "-config %cd%/rel/files/eunit.confi
 just-eunit:
 	@$(REBAR) -r eunit $(EUNIT_OPTS)
 
-# target: erlfmt-check - Check source code formatting
+# target: erlfmt-check - Check Erlang source code formatting
 erlfmt-check: export ERLFMT_PATH := $(ERLFMT)
 erlfmt-check:
 	@$(PYTHON) dev\format_check.py
 
-# target: erlfmt-format - Apply source code format standards automatically
+# target: erlfmt-format - Apply Erlang source code format standards automatically
 erlfmt-format: export ERLFMT_PATH := $(ERLFMT)
 erlfmt-format:
 	@$(PYTHON) dev\format_all.py
@@ -194,7 +194,7 @@ erlfmt-format:
 	@$(PYTHON) -m venv .venv
 	@.venv\Scripts\pip3.exe install black || copy /b .venv\Scripts\black.exe +,,
 
-# target: python-black - Python code formatter, runs only on Python >= 3.6
+# target: python-black - Check Python code formatting (requires Python >= 3.6)
 python-black: .venv/bin/black
 	@$(PYTHON) -c "import sys; exit(1 if sys.version_info < (3,6) else 0)" || \
 		echo 'Python formatter not supported on Python < 3.6; check results on a newer platform'
@@ -203,6 +203,7 @@ python-black: .venv/bin/black
 		--exclude="build/|buck-out/|dist/|_build/|\.git/|\.hg/|\.mypy_cache/|\.nox/|\.tox/|\.venv/|src/erlfmt|src/rebar/pr2relnotes.py|src/fauxton" \
 		build-aux dev\run dev\format_*.py src\mango\test src\docs\src\conf.py src\docs\ext .
 
+# target: python-black-update - Apply Python source code format standards automatically (requires Python >= 3.6)
 python-black-update: .venv/bin/black
 	@$(PYTHON) -c "import sys; exit(1 if sys.version_info < (3,6) else 0)" || \
 		echo 'Python formatter not supported on Python < 3.6; check results on a newer platform'
diff --git a/README-DEV.rst b/README-DEV.rst
index dd527337a..401b76580 100644
--- a/README-DEV.rst
+++ b/README-DEV.rst
@@ -174,7 +174,14 @@ To format the ``erl`` files in ``src``, run ``make erlfmt-format``.
 To use ``erlfmt`` for specific files only, use the executable ``bin/erlfmt``
 that is installed by ``configure``.
 
+Python files throughout the repository should conform to (PEP
+8-compliant) formatting rules as specified by black_.  Similarly to
+``erlfmt``, the related checks are run for every PR in the CI.  The
+same checks could also be run locally via ``make python-black``.
+Files can be automatically formatted by ``make python-black-update``.
+
 .. _erlfmt: https://github.com/WhatsApp/erlfmt
+.. _black: https://github.com/psf/black
 
 Testing
 -------