diff --git a/doc/procedures/pre_commit.rst b/doc/procedures/pre_commit.rst index 0ead3f9..d4f2222 100644 --- a/doc/procedures/pre_commit.rst +++ b/doc/procedures/pre_commit.rst @@ -14,11 +14,14 @@ To enable this: The following pre-commit hooks are used: :black: An opinionated autoformatter. -:isort: An opinionated import sorter. -:flake8: A style checker with many different plugins to enforce different rules. -:check-yaml: Checks yaml files for proper format. :check-xml: Checks xml files for proper format. +:check-yaml: Checks yaml files for proper format. +:clang-format: Format files with ClangFormat. +:flake8: A style checker with many different plugins to enforce different rules. +:format-xmllint: Feed all XML files through xmllint. +:isort: An opinionated import sorter. :mypy: Performs type checking on the code (optional). +:ruff: An extremely fast Python linter, written in Rust. ################## @@ -41,16 +44,20 @@ An example where all ``pre-commit`` hooks are enabled is: .. code-block:: yaml - check-yaml: true - check-xml: true - black: true - flake8: true - isort: true - mypy: true + black: true + check-xml: true + check-yaml: true + clang-format: true + flake8: true + format-xmllint: true + isort: true + mypy: true + ruff: true The ``generate_pre_commit_conf`` command fails with a comprehensive error message if a mandatory or optional ``pre-commit`` hook is missing. All ``pre-commit`` hooks except for ``mypy`` are mandatory for TSSW projects, so those hooks need to be set to ``true``. +The ``clang-format`` and ``ruff`` hooks may be omitted from the ``.ts-pre-commit-config.yaml`` configuration file as they are optional. Setting one or more of the mandatory hooks to ``false`` will make the ``generate_pre_commit_conf`` command fail with a comprehensive error message. The configuration files will be updated whenever the pre-commit hooks get updated. @@ -99,3 +106,27 @@ Then, in all cases, execute these steps: * Changes made by black should never break anything. * Once this is all done, create a git commit to reflect the change with ``git commit -a -m "Use ts_pre_commit_conf."``. + +Adding a new hook +----------------- + +In order to add a new hook, do the following: + +* Create a new ticket branch in the ``ts_pre_commit_conf`` project following the :ref:`development-workflow`. +* Edit the ``lsst/ts/pre_commit_conf/pre_commit_hooks.py`` file. +* Add a new entry to the ``registry`` dict providing the following information: + + * config_file_name: the name of the config file of the hook, or None if the hook doesn't require a config file. + * config: the config file contents as a string. + Provide this as a triple quoted string without leading or trailing whitespace apart from a newline character at the end. + See the other hooks in the registry for examples. + Note that this needs to be set to None if config_file_name is set to None. + * pre_commit_config: the config for the ``.pre-commit-config.yaml`` file. + Provide this as a triple quoted string without leading or trailing whitespace apart from a newline character at the end. + See the other hooks in the registry for examples. + * optional: indicate whether the hook is optional (``True``) or not (``False``). + Setting this to True will still include the hook but will not make the ``generate_pre_commit_conf`` command complain if it is missing. + * excludable: indicate whether the hook can be excluded (``True``) or not (``Talse``). + The difference with optional is that excludable will generate a command line option that allows for actively excluding the hook. + Setting this to ``True`` will generate an entry in the ``.ts-pre-commit-config.yaml`` configuration file for the hook with the value ``false``. + This will also exclude the hook configuration from the ``.pre-commit-config.yaml`` file.