Merging upstream version 0.19.1.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
61e6dccee9
commit
2efee3d3ab
GPG key ID:
FBB4F0E80A80222F
111 changed files with 2058 additions and 1676 deletions
|
|
@ -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
|
|||
|
||||
|
||||
|
||||
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.
|
|||
|
||||
|
||||
|
||||
### 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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue