From 0fe6b8122ae92c3bfcadc7186b0fe5d9355f66c6 Mon Sep 17 00:00:00 2001
From: MDW <mdeweerd@users.noreply.github.com>
Date: Mon, 15 Jan 2024 17:25:06 +0100
Subject: [PATCH] NEW: Dev documentation about setting up pre-commit locally

# NEW: Dev documentation about setting up pre-commit locally

A quick start guide about setting up pre-commit.
---
 dev/setup/README.md            | 10 ++++
 dev/setup/pre-commit/README.md | 85 ++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+)
 create mode 100644 dev/setup/README.md
 create mode 100644 dev/setup/pre-commit/README.md

diff --git a/dev/setup/README.md b/dev/setup/README.md
new file mode 100644
index 00000000000..5bc8fc08a99
--- /dev/null
+++ b/dev/setup/README.md
@@ -0,0 +1,10 @@
+# Setting up for Dolibarr development
+
+Check out the
+[online documentation](https://wiki.dolibarr.org/index.php?title=Environment_and_development_tools)
+for recommendations (to be updated).
+
+If anything, install `pre-commit` - it will help run the tools to format and
+make some basic verifications on your submission before committing and pushing
+to github for a PR. See [a quick start guide](./pre-commit/README.md) in this
+Dolibarr repository.
diff --git a/dev/setup/pre-commit/README.md b/dev/setup/pre-commit/README.md
new file mode 100644
index 00000000000..d0124e23b16
--- /dev/null
+++ b/dev/setup/pre-commit/README.md
@@ -0,0 +1,85 @@
+## 'pre-commit' ("replaces" precommit)
+
+### Introduction
+
+[`pre-commit`](https://pre-commit.org) is a framework for managing and
+maintaining multi-language pre-commit hooks.
+
+"pre-commit hooks" integrate with `git` and are run when you perform a
+`git commit` for instance.
+
+Historically there was `precommit` for Dolibarr which you can find in this
+directory. That script runs `phplint`, `phpcs` and `phpcbf` upon commit.
+
+`pre-commit` is not specific to Dolibarr and is deployed on many projects -
+mostly Python projects, but it is applicable to most (or *all*) code and
+documentation development.
+
+You can find documentation at https://pre-commit.com/ .
+
+Now you can use `pre-commit` which uses the configuration found at the root of
+the project: `pre-commit-config.yaml`.
+
+### How to
+
+1. Install `pre-commit`.\
+   If you do not have python installed, install
+   [python](https://www.python.org) first.\
+   If you do not have
+   [`pip`](https://pypi.org/project/pip), install that as well.\\
+
+   Then you can install pre-commit: `python -m pip install pre-commit`.
+
+1. In you local git clone of the project, run `pre-commit install`. That will
+   add the hooks.
+
+### Tips
+
+After installing `pre-commit` onto your local git clone, pre-commit will run
+on every commit.
+
+When it finds some issue, the git commit will be aborted, so you can fix it,
+or verify it.
+
+The tools run by `pre-commit` may modify your code: format PHP code
+(`phpcbf`), fix line endings, end of files, etc.
+
+They may also alert about potential issues: syntax errors, spelling errors,
+code quality, an execute bit that was (not) set in the git repository, etc.
+
+One way to use it is this:
+
+```bash
+cd PROJECT_DIR
+pre-commit install  # Only needed once
+# Repeat until success.
+git commit -a -m "My message"
+# `pre-commit` is run and reports
+# Check the results, make fixes, and re-commit (=repeat above line).
+```
+
+In some cases you may want to commit despite the changes.\
+You can just add
+`--no-verify` to your git command:
+
+```bash
+git commit -a -m "My message" --no-verify
+```
+
+If you want to skip certain checks for whatever reason, you can set the SKIP
+environment variable:
+
+```bash
+SKIP=no-commit-to-branch git commit -a -m "My message"
+
+or
+
+export SKIP=no-commit-to-branch   # In your .bashrc or session.
+```
+
+There is much more you can do with pre-commit, check out its
+[documentation](https://pre-commit.com).
+
+Now your commit is less likely to fail in the Continuous Intagration (CI) run
+on github.\
+CI also runs pre-commit to help maintain code quality.