docs: update commit message linting documentation

README.md

@@ -156,6 +156,12 @@ Documentation is automatically built and deployed via GitLab CI/CD:
 
 This project uses [gitlint](https://jorisroovers.github.io/gitlint/) to enforce consistent commit message formatting. Commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
 
+The linting is integrated into the development workflow through:
+
+- **Pre-commit hooks**: Automatically validates commit messages when you commit
+- **Manual linting**: Available through standalone scripts for individual commits or ranges
+- **CI/CD integration**: Can be used in continuous integration pipelines
+
 ### Commit Message Format
 
 Commit messages must follow this format:
@@ -209,15 +215,29 @@ python scripts/lint-commit.py --range HEAD~3..
 python scripts/lint-commit.py --install-hook
 ```
 
-### Git Hook Installation
+### Automated Validation with Pre-commit
 
-You can optionally install a git hook that automatically checks commit messages:
+The project includes a pre-commit configuration that automatically validates commit messages:
+
+```bash
+# Install pre-commit hooks (recommended)
+pre-commit install --hook-type commit-msg
+
+# Or install all hooks including code formatting
+pre-commit install
+```
+
+This sets up automatic validation that runs every time you commit, ensuring all commit messages follow the required format.
+
+### Manual Git Hook Installation
+
+Alternatively, you can install a standalone git hook:
 
 ```bash
 python scripts/lint-commit.py --install-hook
 ```
 
-This will create a `commit-msg` hook that runs automatically when you commit, ensuring all commit messages follow the required format.
+This creates a simple `commit-msg` hook that runs gitlint directly.
 
 ## Testing
 
@@ -345,24 +365,32 @@ Contributions are welcome! Please fork the repository and submit a pull request
    pip install -r requirements-dev.txt
    ```
 
-2. Run tests to ensure everything works:
+2. Install pre-commit hooks (recommended):
+
+   ```bash
+   pre-commit install --hook-type commit-msg
+   ```
+
+3. Run tests to ensure everything works:
 
    ```bash
    pytest
    ```
 
-3. Install the git commit message hook (recommended):
+4. Optionally run pre-commit on all files to check formatting:
+
    ```bash
-   python scripts/lint-commit.py --install-hook
+   pre-commit run --all-files
    ```
 
 ### Code Quality
 
-- Follow the existing code style and formatting
+- Follow the existing code style and formatting (enforced by pre-commit hooks)
 - Write tests for new functionality
 - Ensure all tests pass before submitting
 - Use meaningful commit messages following the conventional commits format
-- Run `python scripts/lint-commit.py` to validate commit messages
+- Pre-commit hooks will automatically validate commit messages and code formatting
+- Run `python scripts/lint-commit.py` to manually validate commit messages
 
 ## License
 

docs/source/commit-messages.rst

@@ -134,10 +134,35 @@ The project uses a ``.gitlint`` configuration file that enforces:
 Linting Tools
 -------------
 
+Pre-commit Integration (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The project includes a pre-commit configuration that automatically validates commit messages along with code formatting and other checks:
+
+.. code-block:: bash
+
+    # Install pre-commit hooks for commit message validation
+    pre-commit install --hook-type commit-msg
+
+    # Install all pre-commit hooks (includes code formatting, linting, etc.)
+    pre-commit install
+
+    # Run all pre-commit hooks on all files
+    pre-commit run --all-files
+
+The pre-commit setup includes:
+
+- **Commit message validation** using gitlint
+- **Code formatting** with ruff
+- **Basic file checks** (trailing whitespace, YAML validation, etc.)
+- **Security scanning** with bandit
+
+This is the recommended approach as it provides comprehensive validation and maintains code quality standards.
+
 Manual Linting
 ~~~~~~~~~~~~~~~
 
-Use the provided script to lint commit messages:
+Use the provided script to lint commit messages manually:
 
 .. code-block:: bash
 
@@ -153,16 +178,16 @@ Use the provided script to lint commit messages:
     # Check staged commit message
     python scripts/lint-commit.py --staged
 
-Git Hook Installation
+Standalone Git Hook Installation
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Install an automated git hook to check commit messages:
+Alternatively, install a standalone git hook for commit message validation only:
 
 .. code-block:: bash
 
     python scripts/lint-commit.py --install-hook
 
-This creates a ``commit-msg`` hook that automatically validates commit messages when you commit. The commit will be rejected if the message doesn't meet the requirements.
+This creates a simple ``commit-msg`` hook that runs gitlint directly without the additional pre-commit features.
 
 Direct Gitlint Usage
 ~~~~~~~~~~~~~~~~~~~~
@@ -226,4 +251,28 @@ Integration with CI/CD
 
 The commit message linting can be integrated into CI/CD pipelines to ensure all commits in pull requests follow the standard format. This helps maintain consistency across all contributors.
 
+**Pre-commit.ci Integration**
+
+The project's ``.pre-commit-config.yaml`` includes configuration for `pre-commit.ci <https://pre-commit.ci>`_, which can automatically run checks on pull requests:
+
+.. code-block:: yaml
+
+    ci:
+      autofix_commit_msg: |
+        [pre-commit.ci] auto fixes from pre-commit hooks
+      autofix_prs: true
+      autoupdate_schedule: weekly
+
+**Manual CI Integration**
+
+For custom CI/CD pipelines, you can run the linting manually:
+
+.. code-block:: bash
+
+    # In your CI script
+    pip install -r requirements-dev.txt
+    python scripts/lint-commit.py --range origin/main..HEAD
+
+This will validate all commits in the current branch against the main branch.
+
 For more information on gitlint configuration and advanced usage, see the `official gitlint documentation <https://jorisroovers.github.io/gitlint/>`_.