From ea0b5945862e0b48ffcaa538c695ba765a35c569 Mon Sep 17 00:00:00 2001
From: Alvaro Leiva <aleivag@gmail.com>
Date: Sat, 24 Jan 2026 21:45:11 -0800
Subject: [PATCH] add pre commit hook to run format tests

---
 .github/workflows/ci.yml |  4 +++
 .pre-commit-config.yaml  | 13 ++++++++++
 CONTRIBUTING.md          | 55 ++++++++++++++++++++++++++++++++++++++++
 pyproject.toml           |  1 +
 4 files changed, 73 insertions(+)
 create mode 100644 .pre-commit-config.yaml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index aeb2498..5f4f5bb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,6 +45,10 @@ jobs:
           e2e
     - name: Run isort
       uses: isort/isort-action@v1
+    - name: Formatting hint
+      if: failure()
+      run: |
+        echo "::notice::PROTIP: You can install pre-commit hooks to automatically format your code before each commit. Run 'uv run pre-commit install' and never have to resubmit a PR because of formatting errors! See CONTRIBUTING.md for more details."
 
 
   typing:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..b209047
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^(pystemd|examples|tests|e2e)/
+      - id: ruff-format
+        files: ^(pystemd|examples|tests|e2e)/
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.0
+    hooks:
+      - id: isort
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7fff321..0e9330e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,6 +6,61 @@ possible.
 We use GitHub issues to track public bugs. Please ensure your description is
 clear and has sufficient instructions to be able to reproduce the issue.
 
+## Development setup
+
+### Prerequisites
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it already:
+
+
+### Installing dependencies
+After cloning the repository, install the development dependencies:
+
+```bash
+uv sync --all-extras
+```
+
+### Running tests
+Run the unit tests with:
+
+```bash
+uv run pytest tests
+```
+
+Or with coverage:
+
+```bash
+uv run pytest --cov=pystemd tests
+```
+
+### Running E2E tests
+The E2E tests run in a systemd container using mkosi and are primarily designed
+for CI. To run them locally, you need `mkosi` and `systemd-container` installed.
+See `.github/workflows/e2e-tests.yml` for the full setup. For most contributions,
+unit tests are sufficient.
+
+### Formatting code
+Format your code before submitting a pull request:
+
+```bash
+uv run ruff check --fix pystemd examples tests e2e
+uv run ruff format pystemd examples tests e2e
+uv run isort .
+```
+
+### Type checking
+We use [pyrefly](https://github.com/facebook/pyrefly) for type checking. Run it with:
+
+```bash
+uv run pyrefly check pystemd examples tests
+```
+
+Optionally, you can install pre-commit hooks to automatically format code on
+each commit:
+
+```bash
+uv run pre-commit install
+```
+
 ## Sending a pull request
 Have a fix or feature? Awesome! When you send the pull request we suggest you
 include a build output.
diff --git a/pyproject.toml b/pyproject.toml
index cf2a900..2b111e9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -46,6 +46,7 @@ lint = [
     "ruff",
     "pyrefly",
     "isort",
+    "pre-commit",
 ]
 
 [project.urls]