Merge "[VOL-5329] - Update copyright docs to mention SPDX"
diff --git a/howto/code/lint/pre-commit.rst b/howto/code/lint/pre-commit.rst
index bf52b5c..29d4915 100644
--- a/howto/code/lint/pre-commit.rst
+++ b/howto/code/lint/pre-commit.rst
@@ -12,7 +12,8 @@
- re-indent files
- etc
-## Install
+Install
+-------
.. code:: bash
@@ -30,18 +31,68 @@
% make clean
-## Configuration
+repo:onf-make convenience target
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+VOLTHA repositories that have
+`repo:onf-make <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master>`_
+installed as a git submodule can use the makefile target `pre-commit` to
+create a virtualenv and invoke pre-commit with a single command.
+
+.. code-block:: shell-session
+ :caption: Convenience Target
+
+ % git clone bbsim
+ % cd bbsim
+
+ % Is the repo:onf-make submodule available ?
+ % git config --file .gitmodules --name-only --get-regexp path
+
+ # yes
+ submodule.lf/onf-make.path
+
+ % make pre-commit
+
+Configuration
+-------------
- Each repository contains a yaml config file that controls hooks and linting behavior:
- repo:bbsim/`.pre-commit-config.yaml <https://gerrit.opencord.org/plugins/gitiles/bbsim/+/refs/heads/master/.pre-commit-config.yaml>`__
- A skeleton config is currently being used.
+
+ - Directory exclusions are supported (regex pattern at the end).
+ - Commit hooks can be enabled/disabled as needed per-repository.
+ - Open tickets to track repository cleanup needed.
+
+- Config changes can be made as needed but if new hooks are added or configs
+ change be sure to update the common config file in repo:onf-make and
+ propogate hook edits out to all VOLTHA repositories for consistency.
- Make changes as needed but be sure to propogate them out to all voltha repositories.
- Long term a central repository can be maintained for pre-commit hooks that can be
included as a git submodule to remove duplication and potential for linting variations.
+Source & Dependencies
+---------------------
+
+| Source | Description |
+| ------ | ----------- |
+| `repo:onf-make <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master>`_ | Repository containing makefile targets and common pre-commit config. |
+| `pre-commit <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/commands/pre-commit/>`_ | Makfile targets used to install the pre-commit tool. |
+| `virtualenv <https://gerrit.opencord.org/plugins/gitiles/onf-make/+/refs/heads/master/makefiles/virtualenv/>`_ | These makefiles will install a python virtulenv into sandbox/.venv/. |
+
+.. todo:
+
+- Move .pre-copmmit-config.yaml setup into a standalone repository.
+- Include the repo as a new git submodule.
+- pre-commit config file can then be maintained as a file on disk
+ (per-repository checking for early cleanup) or be replaced with
+ a symlink that references the shared config file. Added benefit
+ -- the submodule also acts as a breadcrumb trail for locating
+ the config for pre-commit edits that span all repositories.
+
.. seealso:
| URL | Description |
-| pre-commit | A framework for managing and maintaining multi-language pre-commit hooks |
+| `pre-commit <https://pre-commit.com/>` | A framework for managing and maintaining multi-language pre-commit hooks |