Merging upstream version 0.18.0.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
0453b640a2
commit
129d2ce1fc
GPG key ID:
FBB4F0E80A80222F
118 changed files with 4146 additions and 2087 deletions
|
|
@ -6,7 +6,7 @@ The [source-code and issue tracker](https://github.com/jorisroovers/gitlint) are
|
|||
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 roadmap on our wiki](https://github.com/jorisroovers/gitlint/wiki/Roadmap), but
|
||||
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
|
||||
|
|
@ -19,11 +19,15 @@ When contributing code, please consider all the parts that are typically require
|
|||
- [Integration tests](https://github.com/jorisroovers/gitlint/tree/main/qa) (also automatically
|
||||
[enforced by CI](https://github.com/jorisroovers/gitlint/actions)). Again, please consider writing new ones
|
||||
for your functionality, not only updating existing ones to make the build pass.
|
||||
- [Documentation](https://github.com/jorisroovers/gitlint/tree/main/docs)
|
||||
- [Documentation](https://github.com/jorisroovers/gitlint/tree/main/docs).
|
||||
|
||||
Since we want to maintain a high standard of quality, all of these things will have to be done regardless before code
|
||||
can make it as part of a release. 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. Thanks!
|
||||
can make it as part of a release. **Gitlint commits and pull requests are gated on all of our tests and checks as well as
|
||||
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
|
||||
**On the topic of releases**: Gitlint releases typically go out when there's either enough new features and fixes
|
||||
|
|
@ -32,55 +36,105 @@ and it's likely that your PR will be merged and released a lot sooner. Thanks!
|
|||
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.
|
||||
|
||||
## Development
|
||||
## Local setup
|
||||
|
||||
There is a Vagrantfile (Ubuntu) in this repository that can be used for development.
|
||||
It comes pre-installed with all Python versions that gitlint supports.
|
||||
```sh
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
```
|
||||
|
||||
Or you can choose to use your local environment:
|
||||
To install gitlint for local development:
|
||||
|
||||
```sh
|
||||
python -m venv .venv
|
||||
. .venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -r requirements.txt -r test-requirements.txt -r doc-requirements.txt
|
||||
python setup.py develop
|
||||
```
|
||||
|
||||
To run tests:
|
||||
## Github Devcontainer
|
||||
|
||||
We provide a devcontainer on github to make it easier to get started with gitlint development using VSCode.
|
||||
|
||||
To start one, click the plus button under the *Code* dropdown on
|
||||
[the gitlint repo on github](https://github.com/jorisroovers/gitlint).
|
||||
|
||||
**It can take ~15min for all post installation steps to finish.**
|
||||
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
# Ensure ASDF overrides system python in PATH
|
||||
# You can also append this line to your ~/.bash_profile in the devcontainer to have this happen automatically on login
|
||||
source "$(brew --prefix asdf)/libexec/asdf.sh"
|
||||
|
||||
# Install python 3.9.15
|
||||
asdf install python 3.9.15
|
||||
# List all available python versions
|
||||
asdf list all python
|
||||
# List installed python versions
|
||||
asdf list python
|
||||
```
|
||||
|
||||
## Running tests
|
||||
```sh
|
||||
./run_tests.sh # run unit tests and print test coverage
|
||||
./run_tests.sh gitlint/tests/rules/test_body_rules.py::BodyRuleTests::test_body_missing # run a single test
|
||||
./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 --pep8 # pep8 checks
|
||||
./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, pep8 and gitlint checks
|
||||
./run_tests.sh --all # Run unit, integration, format and gitlint checks
|
||||
```
|
||||
## Formatting
|
||||
|
||||
We use [black](https://black.readthedocs.io/en/stable/) for code formatting.
|
||||
To use it, just run black against the code you modified:
|
||||
|
||||
The `Vagrantfile` comes with `virtualenv`s for python 3.6, 3.7, 3.8, 3.9 and pypy3.6.
|
||||
You can easily run tests against specific python environments by using the following commands *inside* of the Vagrant VM:
|
||||
```sh
|
||||
./run_tests.sh --envs 36 # Run the unit tests against Python 3.6
|
||||
./run_tests.sh --envs 36,37,pypy36 # Run the unit tests against Python 3.6, Python 3.7 and Pypy3.6
|
||||
./run_tests.sh --envs 36,37 --pep8 # Run pep8 checks against Python 3.6 and Python 3.7 (also works for --git, --integration, --pep8, --stats and --lint.
|
||||
./run_tests.sh --envs all --all # Run all tests against all environments
|
||||
./run_tests.sh --all-env --all # Idem: Run all tests against all environments
|
||||
black . # format all python code
|
||||
black gitlint-core/gitlint/lint.py # format a specific file
|
||||
```
|
||||
|
||||
!!! important
|
||||
Gitlint commits and pull requests are gated on all of our tests and checks.
|
||||
## Documentation
|
||||
We use [mkdocs](https://www.mkdocs.org/) for generating our documentation from markdown.
|
||||
|
||||
To use it:
|
||||
```sh
|
||||
pip install -r doc-requirements.txt # install doc requirements
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Then access the documentation website on [http://localhost:8000]().
|
||||
|
||||
## Packaging
|
||||
|
||||
Gitlint consists of 2 python packages: [gitlint](https://pypi.org/project/gitlint/)
|
||||
and [gitlint-core](https://pypi.org/project/gitlint-core/).
|
||||
|
||||
The `gitlint` package is just a wrapper package around `gitlint-core[trusted-deps]` which strictly pins gitlint
|
||||
dependencies to known working versions.
|
||||
|
||||
There are scenarios where users (or OS package managers) may want looser dependency requirements.
|
||||
In these cases, users can just install `gitlint-core` directly (`pip install gitlint-core`).
|
||||
|
||||
[Issue 162](https://github.com/jorisroovers/gitlint/issues/162) has all the background of how we got to the decision
|
||||
to split gitlint in 2 packages.
|
||||
|
||||
|
||||
|
||||
### Packaging description
|
||||
|
||||
To see the package description in HTML format
|
||||
```sh
|
||||
pip install docutils
|
||||
|
|
@ -89,16 +143,6 @@ export LANG=en_US.UTF-8
|
|||
python setup.py --long-description | rst2html.py > output.html
|
||||
```
|
||||
|
||||
## Documentation
|
||||
We use [mkdocs](https://www.mkdocs.org/) for generating our documentation from markdown.
|
||||
|
||||
To use it, do the following outside of the vagrant box (on your host machine):
|
||||
```sh
|
||||
pip install -r doc-requirements.txt # install doc requirements
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Then access the documentation website on your host machine on [http://localhost:8000]().
|
||||
|
||||
## Tools
|
||||
We keep a small set of scripts in the `tools/` directory:
|
||||
|
|
@ -110,13 +154,13 @@ tools/windows/run_tests.bat # Windows run unit tests
|
|||
```
|
||||
|
||||
## Contrib rules
|
||||
Since gitlint 0.12.0, we support [Contrib rules](../contrib_rules): community contributed rules that are part of gitlint
|
||||
Since gitlint 0.12.0, we support [Contrib rules](contrib_rules.md): community contributed rules that are part of gitlint
|
||||
itself. Thanks for considering to add a new one to gitlint!
|
||||
|
||||
Before starting, please read all the other documentation on this page about contributing first.
|
||||
Then, we suggest taking the following approach to add a Contrib rule:
|
||||
|
||||
1. **Write your rule as a [user-defined rule](../user_defined_rules)**. In terms of code, Contrib rules are identical to
|
||||
1. **Write your rule as a [user-defined rule](user_defined_rules.md)**. In terms of code, Contrib rules are identical to
|
||||
user-defined rules, they just happen to have their code sit within the gitlint codebase itself.
|
||||
2. **Add your user-defined rule to gitlint**. You should put your file(s) in the [gitlint/contrib/rules](https://github.com/jorisroovers/gitlint/tree/main/gitlint-core/gitlint/contrib/rules) directory.
|
||||
3. **Write unit tests**. The gitlint codebase contains [Contrib rule test files you can copy and modify](https://github.com/jorisroovers/gitlint/tree/main/gitlint-core/gitlint/tests/contrib/rules).
|
||||
|
|
@ -129,7 +173,7 @@ If you follow the steps above and follow the existing gitlint conventions wrt na
|
|||
|
||||
In case you're looking for a slightly more formal spec, here's what gitlint requires of Contrib rules.
|
||||
|
||||
- Since Contrib rules are really just user-defined rules that live within the gitlint code-base, all the [user-rule requirements](../user_defined_rules/#rule-requirements) also apply to Contrib rules.
|
||||
- Since Contrib rules are really just user-defined rules that live within the gitlint code-base, all the [user-rule requirements](user_defined_rules.md#rule-requirements) also apply to Contrib rules.
|
||||
- All contrib rules **must** have associated unit tests. We *sort of* enforce this by a unit test that verifies that there's a
|
||||
test file for each contrib file.
|
||||
- All contrib rules **must** have names that start with `contrib-`. This is to easily distinguish them from default gitlint rules.
|
||||
|
|
@ -137,4 +181,4 @@ In case you're looking for a slightly more formal spec, here's what gitlint requ
|
|||
- All contrib rules **must** have unique names and ids.
|
||||
- You **can** add multiple rule classes to the same file, but classes **should** be logically grouped together in a single file that implements related rules.
|
||||
- Contrib rules **should** be meaningfully different from one another. If a behavior change or tweak can be added to an existing rule by adding options, that should be considered first. However, large [god classes](https://en.wikipedia.org/wiki/God_object) that implement multiple rules in a single class should obviously also be avoided.
|
||||
- Contrib rules **should** use [options](../user_defined_rules/#options) to make rules configurable.
|
||||
- Contrib rules **should** use [options](user_defined_rules.md#options) to make rules configurable.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue