diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/contributing.md | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..0cd6eaf --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,132 @@ +# Contributing + +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 roadmap on our wiki](https://github.com/jorisroovers/gitlint/wiki/Roadmap), but +that's open to a lot of change and input. + +# Guidelines + +When contributing code, please consider all the parts that are typically required: + +- [Unit tests](https://github.com/jorisroovers/gitlint/tree/master/gitlint/tests) (automatically + [enforced by CI](https://github.com/jorisroovers/gitlint/actions)). Please consider writing + new ones for your functionality, not only updating existing ones to make the build pass. +- [Integration tests](https://github.com/jorisroovers/gitlint/tree/master/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/master/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! + +# Development # + +There is a Vagrantfile in this repository that can be used for development. +```bash +vagrant up +vagrant ssh +``` + +Or you can choose to use your local environment: + +```bash +virtualenv .venv +pip install -r requirements.txt -r test-requirements.txt -r doc-requirements.txt +python setup.py develop +``` + +To run tests: +```bash +./run_tests.sh # run unit tests and print test coverage +./run_test.sh gitlint/tests/test_body_rules.py::BodyRuleTests::test_body_missing # run a single test +./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 --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 + + +``` + +The ```Vagrantfile``` comes with ```virtualenv```s for python 2.7, 3.5, 3.6, 3.7 and pypy2. +You can easily run tests against specific python environments by using the following commands *inside* of the Vagrant VM: +``` +./run_tests.sh --envs 27 # Run the unit tests against Python 2.7 +./run_tests.sh --envs 27,35,pypy2 # Run the unit tests against Python 2.7, Python 3.5 and Pypy2 +./run_tests.sh --envs 27,35 --pep8 # Run pep8 checks against Python 2.7 and Python 3.5 (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 +``` + +!!! important + Gitlint commits and pull requests are gated on all of our tests and checks. + +# Packaging # + +To see the package description in HTML format +``` +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 +``` + +# 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): +```bash +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: + +```sh +tools/create-test-repo.sh # Create a test git repo in your /tmp directory +tools/windows/create-test-repo.bat # Windows: create git test repo +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 +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 + 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/master/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/master/gitlint/tests/contrib). +4. **Write documentation**. In particular, you should update the [gitlint/docs/contrib_rules.md](https://github.com/jorisroovers/gitlint/blob/master/docs/contrib_rules.md) file with details on your Contrib rule. +5. **Create a Pull Request**: code review typically requires a bit of back and forth. Thanks for your contribution! + + +## Contrib rule requirements +If you follow the steps above and follow the existing gitlint conventions wrt naming things, you should already be fairly close to done. + +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. +- 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. +- All contrib rule ids **must** start with `CT` (for LineRules targeting the title), `CB` (for LineRules targeting the body) or `CC` (for CommitRules). Again, this is to easily distinguish them from default gitlint rules. +- 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. |