diff options
Diffstat (limited to 'docs/contributing.md')
| -rw-r--r-- | docs/contributing.md | 135 |
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  -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.  -### 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: |