howto/code/lint/pre-commit.rst

.. _Makefile Target lint-pre-commit:

Tool: pre-commit
================

The `pre-commit tool <https://pre-commit.com/>`__ can also be used to:

- Scan for a variety of problems: syntax, licensing, etc.
- Perform some code cleanups

  - Remove whitespace
  - re-indent files
  - etc

Install
-------

.. code:: bash

    % git clone ssh://gerrit.opencord.org:29418/bbsim.git
    % cd bbsim

    % make help

    # Install python virtualenv w/modules from requirements.txt
    % make venv
    % source .venv/bin/activate

    # Scan for problems
    % pre-commit

    % make clean

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 <https://pre-commit.com/>` | A framework for managing and maintaining multi-language pre-commit hooks |