Merging upstream version 0.19.1.

Signed-off-by: Daniel Baumann <daniel@debian.org>
2025-02-13 06:07:32 +01:00 · 2025-02-13 06:07:32 +01:00 · 2efee3d3ab
commit 2efee3d3ab
parent 61e6dccee9
111 changed files with 2058 additions and 1676 deletions
--- a/docs/contributing.md
+++ b/docs/contributing.md
@ -3,13 +3,14 @@
 We'd love for you to contribute to gitlint. Thanks for your interest!
 The [source-code and issue tracker](https://github.com/jorisroovers/gitlint) are hosted on Github.

-Often it takes a while for us (well, actually just [me](https://github.com/jorisroovers)) to get back to you
-(sometimes up to a few months, this is a hobby project), but rest assured that we read your message and appreciate
-your interest!
-We maintain a [loose project plan on github projects](https://github.com/users/jorisroovers/projects/1/), but
-that's open to a lot of change and input.
+!!! note
+    Often it takes a while for us (well, actually just [me](https://github.com/jorisroovers)) to get back to you
+    (sometimes up to a few months, this is a hobby project), but rest assured that we read your message and appreciate
+    your interest!
+    We maintain a [loose project plan on github projects](https://github.com/users/jorisroovers/projects/1/), but
+    that's open to a lot of change and input.

-## Guidelines
+## Overall Guidelines

 When contributing code, please consider all the parts that are typically required:

@ -26,28 +27,46 @@ can make it as part of a release. **Gitlint commits and pull requests are gated
 code-review**. If you can already include them as part of your PR, it's a huge timesaver for us
 and it's likely that your PR will be merged and released a lot sooner. 

-It's also a good idea to open an issue before submitting a PR for non-trivial changes, so we can discuss what you have
-in mind before you spend the effort. Thanks!
+!!! important
+    It's a good idea to open an issue before submitting a PR for non-trivial changes, so we can discuss what you have
+    in mind before you spend the effort. Thanks!

-!!! Important
-    **On the topic of releases**: Gitlint releases typically go out when there's either enough new features and fixes
-    to make it worthwhile or when there's a critical fix for a bug that fundamentally breaks gitlint. While the amount
-    of overhead of doing a release isn't huge, it's also not zero. In practice this means that it might take weeks
-    or months before merged code actually gets released - we know that can be frustrating but please understand it's
-    a well-considered trade-off based on available time.
+## Releases
+Gitlint releases typically go out when there's either enough new features and fixes
+to make it worthwhile or when there's a critical fix for a bug that fundamentally breaks gitlint.

-## Local setup
+While the amount of overhead of doing a release isn't huge, it's also not zero. In practice this means that it might
+take weeks or months before merged code actually gets released - we know that can be frustrating but please
+understand it's a well-considered trade-off based on available time.

-To install gitlint for local development:
+### Dev Builds
+While final releases are usually months apart, we do dev builds on every commit to `main`:

+- **gitlint**: [https://pypi.org/project/gitlint/#history](https://pypi.org/project/gitlint/#history)
+- **gitlint-core**:  [https://pypi.org/project/gitlint-core/#history](https://pypi.org/project/gitlint-core/#history)
+
+It usually takes about 5 min after merging a PR to `main` for new dev builds to show up. Note that the installation
+of a recently published version can still fail for a few minutes after a new version shows up on PyPI while the package
+is replicated to all download mirrors.
+
+To install a dev build of gitlint:
 ```sh
-python -m venv .venv
-. .venv/bin/activate
-pip install -r requirements.txt -r test-requirements.txt -r doc-requirements.txt
-python setup.py develop
+# Find latest dev build on https://pypi.org/project/gitlint/#history
+pip install gitlint=="0.19.0.dev68"
 ```

-## Github Devcontainer
+
+## Environment setup
+### Local setup
+
+Gitlint uses [hatch](https://hatch.pypa.io/latest/) for project management.
+You do not need to setup a `virtualenv`, hatch will take care of that for you.
+
+```sh
+pip install hatch
+```
+
+### Github Devcontainer

 We provide a devcontainer on github to make it easier to get started with gitlint development using VSCode.

@ -59,12 +78,6 @@ To start one, click the plus button under the *Code* dropdown on
 ![Gitlint Dev Container Instructions](images/dev-container.png)


-After setup has finished, you should be able to just activate the virtualenv in the home dir and run the tests:
-```sh
-. ~/.venv/bin/activate
-./run_tests.sh
-```
-
 By default we have python 3.11 installed in the dev container, but you can also use [asdf](https://asdf-vm.com/)
 (preinstalled) to install additional python versions:

@ -83,27 +96,43 @@ asdf list python

 ## Running tests
 ```sh
-./run_tests.sh                       # run unit tests and print test coverage
-./run_tests.sh gitlint-core/gitlint/tests/rules/test_body_rules.py::BodyRuleTests::test_body_missing # run a single test
-pytest -k test_body_missing          # Alternative way to run a specific test by invoking pytest directly with a keyword expression
-./run_tests.sh --no-coverage         # run unit tests without test coverage
-./run_tests.sh --collect-only --no-coverage  # Only collect, don't run unit tests
-./run_tests.sh --integration         # Run integration tests (requires that you have gitlint installed)
-./run_tests.sh --build               # Run build tests (=build python package)
-./run_tests.sh --format              # format checks (black)
-./run_tests.sh --stats               # print some code stats
-./run_tests.sh --git                 # inception: run gitlint against itself
-./run_tests.sh --lint                # run pylint checks
-./run_tests.sh --all                 # Run unit, integration, format and gitlint checks
+# Gitlint
+hatch run dev:gitlint            # run the local source copy of gitlint
+hatch run dev:gitlint --version  # This is just the gitlint binary, any flag will work
+hatch run dev:gitlint --debug       
+
+# Unit tests
+hatch run test:unit-tests        # run unit tests
+hatch run test:unit-tests gitlint-core/gitlint/tests/rules/test_body_rules.py::BodyRuleTests::test_body_missing # run a single test
+hatch run test:unit-tests -k test_body_missing_merge_commit # Run a specific tests using a pytest keyword expression
+hatch run test:unit-tests-no-cov # run unit tests without test coverage
+
+# Integration tests
+hatch run qa:install-local       # One-time install: install the local gitlint source copy for integration testing
+hatch run qa:integration-tests   # Run integration tests
+
+# Formatting check (black)
+hatch run test:format            # Run formatting checks
+
+#  Linting (ruff)
+hatch run test:lint              # Run Ruff
+
+# Project stats
+hatch run test:stats
 ```
-## Formatting
+## Autoformatting and autofixing

 We use [black](https://black.readthedocs.io/en/stable/) for code formatting.
-To use it, just run black against the code you modified:

 ```sh
-black . # format all python code
-black gitlint-core/gitlint/lint.py # format a specific file
+hatch run test:autoformat                              # format all python code
+hatch run test:autoformat gitlint-core/gitlint/lint.py # format a specific file
+```
+
+We use [ruff](https://github.com/charliermarsh/ruff) for linting, it can autofix many of the issue it finds
+(although not always perfect).
+```sh
+hatch run test:autofix                              # Attempt to fix linting issues
 ```

 ## Documentation
@ -111,8 +140,7 @@ We use [mkdocs](https://www.mkdocs.org/) for generating our documentation from m

 To use it:
 ```sh
-pip install -r doc-requirements.txt # install doc requirements
-mkdocs serve
+hatch run docs:serve
 ```

 Then access the documentation website on [http://localhost:8000]().
@ -133,16 +161,17 @@ to split gitlint in 2 packages.

 ![Gitlint package structure](images/gitlint-packages.png)

-### Packaging description
-
-To see the package description in HTML format
+To build the packages locally:
 ```sh
-pip install docutils
-export LC_ALL=en_US.UTF-8
-export LANG=en_US.UTF-8
-python setup.py --long-description | rst2html.py > output.html
-```
+# gitlint
+hatch build
+hatch clean # cleanup

+# gitlint-core
+cd gitlint-core
+hatch build
+hatch clean # cleanup
+```

 ## Tools
 We keep a small set of scripts in the `tools/` directory:
--- a/docs/index.md
+++ b/docs/index.md
@ -7,7 +7,7 @@ Great for use as a [commit-msg git hook](#using-gitlint-as-a-commit-msg-hook) or
 <script type="text/javascript" src="https://asciinema.org/a/30477.js" id="asciicast-30477" async></script>

 !!! note
-    **Gitlint support for Windows is experimental**, and [there are some known issues](https://github.com/jorisroovers/gitlint/issues?q=is%3Aissue+is%3Aopen+label%3Awindows).
+    **Gitlint works on Windows**, but [there are some known issues](https://github.com/jorisroovers/gitlint/issues?q=is%3Aissue+is%3Aopen+label%3Awindows).

    Also, gitlint is not the only git commit message linter out there, if you are looking for an alternative written in a different language,
    have a look at [fit-commit](https://github.com/m1foley/fit-commit) (Ruby),
@ -15,7 +15,7 @@ Great for use as a [commit-msg git hook](#using-gitlint-as-a-commit-msg-hook) or


 !!! important
-    **Gitlint no longer supports Python 2.7 and Python 3.5 as they [have reached End-Of-Life](https://endoflife.date/python). The last gitlint version to support Python 2.7 and Python 3.5 is `0.14.0` (released on October 24th, 2020).**
+    **Gitlint requires Python 3.7 (or above). For Python 2.7 and Python 3.5 use `gitlint==0.14.0` (released 2020-10-24), for Python 3.6 `gitlint==0.18.0` (released 2022-11-16).**

 ## Features
 - **Commit message hook**: [Auto-trigger validations against new commit message right when you're committing](#using-gitlint-as-a-commit-msg-hook). Also [works with pre-commit](#using-gitlint-through-pre-commit).
@ -30,7 +30,8 @@ useful throughout the years.
 - **User-defined rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules.md).
 - **Full unicode support:** Lint your Russian, Chinese or Emoji commit messages with ease!
 - **Production-ready:** Gitlint checks a lot of the boxes you're looking for: actively maintained, high unit test coverage, integration tests,
-   python code standards (pep8, pylint), good documentation, widely used, proven track record.
+   python code standards ([black](https://github.com/psf/black), [ruff](https://github.com/charliermarsh/ruff)),
+   good documentation, widely used, proven track record.

 ## Getting Started
 ### Installation
@ -271,7 +272,7 @@ If you want to lint more commits you can modify the `gitlint-ci` hook like so:

 ```yaml
 -   repo: https://github.com/jorisroovers/gitlint
-    rev:  v0.17.0
+    rev:  # insert ref, e.g. v0.18.0
    hooks:
    -   id: gitlint
    -   id: gitlint-ci
@ -317,12 +318,14 @@ gitlint --commits mybranch
 # Lint all commits that are different between a branch and your main branch
 gitlint --commits "main..mybranch"
 # Use git's special references
-gitlint --commits "origin..HEAD"
+gitlint --commits "origin/main..HEAD"

 # You can also pass multiple, comma separated commit hashes:
 gitlint --commits 019cf40,c50eb150,d6bc75a
 # These can include special references as well
 gitlint --commits HEAD~1,mybranch-name,origin/main,d6bc75a
+# You can also lint a single commit with --commits:
+gitling --commits 019cf40,
 ```

 The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood
@ -331,6 +334,7 @@ by [git rev-list](https://git-scm.com/docs/git-rev-list) as a single argument wi
 Alternatively, you can pass `--commits` a comma-separated list of commit hashes (both short and full-length SHAs work,
 as well as special references such as `HEAD` and branch names).
 Gitlint will treat these as pointers to **single** commits and lint these in the order you passed.
+`--commits` also accepts a single commit SHA with a trailing comma. 

 For cases where the `--commits` option doesn't provide the flexibility you need, you can always use a simple shell
 script to lint an arbitrary set of commits, like shown in the example below.