summaryrefslogtreecommitdiffstats
path: root/docs/contributing.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/contributing.md135
1 files changed, 82 insertions, 53 deletions
diff --git a/docs/contributing.md b/docs/contributing.md
index 254e856..d111bc6 100644
--- 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,17 +161,18 @@ 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: