tools/format-cpp: exclude generated `parser.*` and `lexer.*` files

[babeltrace.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 945f3984d368406d3a9d96fa86dffd12f640eb4f..d5241ff4a8d611b924a9713f94116d292059cbc9 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -439,7 +439,6 @@ level, for example:
 +
 [source,c]
 ----
-BT_HIDDEN
 char *bt_common_get_home_plugin_path(int log_level);
 ----
 +
@@ -585,10 +584,6 @@ of `+BT_LOG*()+`:
     Library error logging statement, and unconditional error cause
     appending.
 
-`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
-    Library fatal logging statement, and unconditional error cause
-    appending.
-
 The macros above accept the typical `printf()` conversion specifiers
 with the following limitations:
 
@@ -1152,7 +1147,6 @@ struct my_comp {
     /* ... */
 };
 
-BT_HIDDEN
 bt_self_component_status my_comp_init(
         bt_self_component_source *self_comp_src,
         bt_value *params, void *init_method_data)
@@ -1497,7 +1491,7 @@ tests to run in, so nothing more is needed.
 If building in-tree, you can run single tests from the tree directly:
 
 ----
-$ ./tests/plugins/sink.text.pretty/test_enum
+$ ./tests/plugins/sink.text.pretty/test-enum.sh
 ----
 
 If building out-of-tree, you can get the appropriate environment by sourcing
@@ -1506,15 +1500,16 @@ want to run tests.
 
 ----
 $ source /path/to/my/build/tests/utils/env.sh
-$ ./tests/plugins/sink.text.pretty/test_enum
+$ ./tests/plugins/sink.text.pretty/test-enum.sh
 ----
 
 ==== Python
 
-You can use the `tests/utils/run_python_bt2` script to run any command
-within an environment making the build's `bt2` Python package available.
+You can use the `tests/utils/run-python-bt2.sh` script to run any
+command within an environment making the build's `bt2` Python package
+available.
 
-`run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
+`run-python-bt2.sh` uses <<test-env,`utils.sh`>> which needs to know the
 build directory, so make sure you set the `BT_TESTS_BUILDDIR`
 environment variable correctly _if you build out of tree_, for example:
 
@@ -1523,10 +1518,10 @@ $ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
 ----
 
 You can run any command which needs the `bt2` Python package through
-`run_python_bt2`, for example:
+`run-python-bt2.sh`, for example:
 
 ----
-$ ./tests/utils/run_python_bt2 ipython3
+$ ./tests/utils/run-python-bt2.sh ipython3
 ----
 
 === Report format
@@ -1572,13 +1567,13 @@ To run all the `bt2` Python package tests:
 * Run:
 +
 ----
-$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
+$ ./tests/utils/run-python-bt2.sh ./tests/bindings/python/bt2/test-python-bt2.sh
 ----
 +
 or:
 +
 ----
-$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+$ ./tests/utils/run-python-bt2.sh python3 ./tests/utils/python/testrunner.py \
   ./tests/bindings/python/bt2/ -p '*.py'
 ----
 
@@ -1588,7 +1583,7 @@ To run **all the tests** in a test module (for example,
 * Run:
 +
 ----
-$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+$ ./tests/utils/run-python-bt2.sh python3 ./tests/utils/python/testrunner.py \
   ./tests/bindings/python/bt2 -t test_value
 ----
 
@@ -1598,7 +1593,7 @@ To run a **specific test case** (for example, `RealValueTestCase` within
 * Run:
 +
 ----
-$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+$ ./tests/utils/run-python-bt2.sh python3 ./tests/utils/python/testrunner.py \
   ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
 ----
 
@@ -1608,7 +1603,7 @@ To run a **specific test** (for example,
 * Run:
 +
 ----
-$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+$ ./tests/utils/run-python-bt2.sh python3 ./tests/utils/python/testrunner.py \
   ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
 ----
 
@@ -1680,8 +1675,7 @@ https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
 You _must_ format modified and new {cpp} files with clang-format before
 you create a contribution patch.
 
-You need clang-format{nbsp}≥{nbsp}10 to use the project's `.clang-format`
-file.
+You need clang-format{nbsp}15 to use the project's `.clang-format` file.
 
 To automatically format all the project's {cpp} files, run:
 
@@ -1689,11 +1683,17 @@ To automatically format all the project's {cpp} files, run:
 $ ./tools/format-cpp
 ----
 
+Pass a directory path to only format the {cpp} files it contains:
+
+----
+$ ./tools/format-cpp ./src/cli
+----
+
 Use the `FORMATTER` environment variable to override the default
 formatter (`clang-format{nbsp}-i`):
 
 ----
-$ FORMATTER='clang-format-10 -i' ./tools/format-cpp
+$ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp
 ----
 
 ==== Naming
@@ -1955,3 +1955,13 @@ private:
 #endif // BABELTRACE_BABY_HPP
 ----
 ====
+
+== Python Usage
+
+=== Formatting
+
+All Python code must be formatted using the version of
+https://github.com/psf/black[Black] specified in `dev-requirements.txt`.
+
+All Python imports must be sorted using the version of
+https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`.