From f4ed17facfbddacf78572998ca69a3663599b52d Mon Sep 17 00:00:00 2001 From: Alexander Minges Date: Mon, 14 Jul 2025 09:40:05 +0200 Subject: [PATCH] docs: update commit message linting documentation --- README.md | 44 +++++++++++++++++++----- docs/source/commit-messages.rst | 59 ++++++++++++++++++++++++++++++--- 2 files changed, 90 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c664f98..de5dedf 100644 --- a/README.md +++ b/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 diff --git a/docs/source/commit-messages.rst b/docs/source/commit-messages.rst index b5388dd..4f8aaa5 100644 --- a/docs/source/commit-messages.rst +++ b/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 `_, 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 `_.