documentation

docs/contributing/lint.md

@@ -1,8 +1,43 @@
-# Image Lint
+# Lint
+
+In order to enforce some rules **linters** are used in this project.
+Linters can be run either during the **development phase** (by the developer) and during **integration phase** (by Travis).
+To integrate and enforce this process in the project lifecycle we are using **git hooks** through [pre-commit][pre-commit].
+
+## Pre-commit hook
+
+### Installation
+
+pre-commit is a Python package that needs to be installed. 
+This can be achieved by using the generic task used to install all Python development dependencies.
+
+```sh
+# Install all development dependencies for the project
+$ make dev-env
+# It can also be installed directly
+$ pip install pre-commit
+```
+
+Then the git hooks scripts configured for the project in `.pre-commit-config.yaml` need to be installed in the local git repository.
+
+```sh
+$ make pre-commit-install 
+```
+
+### Run
+
+Now pre-commit (and so configured hooks) will run automatically on `git commit` on each changed file.
+However it is also possible to trigger it against all files.
+
+```sh
+$ make pre-commit-all
+```
+
+## Image Lint
 
 To comply with [Docker best practices][dbp], we are using the [Hadolint][hadolint] tool to analyse each `Dockerfile` .
 
-## Installation
+### Installation
 
 There is a specific `make` target to install the linter.
 By default `hadolint` will be installed in `${HOME}/hadolint`.
@@ -15,9 +50,9 @@ $ make lint-install
 # Haskell Dockerfile Linter v1.17.6-0-gc918759
 ```
 
-## Lint
+### Linting
 
-### Per Stack
+#### Per Stack
 
 The linter can be run per stack.
 
@@ -41,7 +76,7 @@ Optionally you can pass arguments to the linter.
 $ make lint/scipy-notebook ARGS="--format codeclimate"  
 ```
 
-### All the Stacks
+#### All the Stacks
 
 The linter can be run against all the stacks.
 
@@ -49,7 +84,7 @@ The linter can be run against all the stacks.
 $ make lint-all
 ```
 
-## Ignoring Rules
+### Ignoring Rules
 
 Sometimes it is necessary to ignore [some rules][rules]. 
 The following rules are ignored by default and sor for all images in the `.hadolint.yaml` file.
@@ -76,3 +111,4 @@ RUN cd /tmp && echo "hello!"
 [rules]: https://github.com/hadolint/hadolint#rules
 [DL3006]: https://github.com/hadolint/hadolint/wiki/DL3006
 [DL3008]: https://github.com/hadolint/hadolint/wiki/DL3008
+[pre-commit]: https://pre-commit.com/