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 |