Documentation updates

- Changed links to point to the main branch instead of master where required
- Various minor doc tweaks
- Updated CHANGELOG for upcoming 0.14.0 release

Author: jorisroovers

CHANGELOG.md

@@ -1,23 +1,36 @@
 # Changelog #
 
-## v0.14.0 (TBD) ##
-- **IMPORTANT:** Gitlint 0.14.x will be the last gitlint release to support Python 2.7 and Python 3.5, as [both are EOL](https://endoflife.date/python) which makes them hard to keep supporting. 
-- [Named Rules](TODO) allow users to have multiple instances of the same rule active at the same time. This is useful when you want to enforce the same rule multiple times but with different options.
-- [User-defined Configuration Rules](TODO) allow users to dynamically change gitlint's configuration and/or the commit *before* any other rules are applied.
+## v0.14.0 (2020-10-24) ##
+
+Contributors:
+Special thanks to all contributors for this release, in particular [@mrshu](https://github.com/mrshu), [@glasserc](https://github.com/glasserc), [@strk](https://github.com/strk), [@chgl](https://github.com/chgl), [@melg8](https://github.com/melg8) and [@sigmavirus24](https://github.com/sigmavirus24).
+
+
+- **IMPORTANT: Gitlint 0.14.x will be the last gitlint release to support Python 2.7 and Python 3.5, as [both are EOL](https://endoflife.date/python) which makes it difficult to keep supporting them.**
 - Python 3.9 support
-- Most general options can now be set through environment variables (e.g. set the `general.ignore` option via `GITLINT_IGNORE=T1,T2`). The list of available environment variables can be found in the [configuration documentation](TODO).
-- Users can now use `self.log.debug("my message")` for debugging purposes in their user-defined rules
-- Breaking: User-defined rule id's can no longer start with 'I', as those are reserved for built-in gitlint ignore rules.
-- **New Rule**: [title-min-length](TODO) enforces a minimum length on titles (default: 5 chars) ([#130](https://github.com/jorisroovers/gitlint/issues/138))
-- **New Rule**: [ignore-body-lines](TODO) allows users to
-[ignore parts of a commit](http://jorisroovers.github.io/gitlint/#ignoring-commits) by matching a regex against
-the lines in a commit message body. ([#126](https://github.com/jorisroovers/gitlint/issues/126)).
-- **New Rule**: [body-match-regex](TODO) allows users to enforce that the commit-msg body matches a given regex ([#130](https://github.com/jorisroovers/gitlint/issues/126))
+- **New Rule**: [title-min-length](http://jorisroovers.github.io/gitlint/rules/#t8-title-min-length) enforces a minimum length on titles (default: 5 chars) ([#138](https://github.com/jorisroovers/gitlint/issues/138))
+- **New Rule**: [body-match-regex](http://jorisroovers.github.io/gitlint/rules/#b8-body-match-regex) allows users to enforce that the commit-msg body matches a given regex ([#130](https://github.com/jorisroovers/gitlint/issues/130))
+- **New Rule**: [ignore-body-lines](http://jorisroovers.github.io/gitlint/rules/#i3-ignore-body-lines) allows users to
+[ignore parts of a commit](http://jorisroovers.github.io/gitlint/gitlint/#ignoring-commits) by matching a regex against
+the lines in a commit message body ([#126](https://github.com/jorisroovers/gitlint/issues/126))
+- [Named Rules](http://jorisroovers.github.io/gitlint/#named-rules) allow users to have multiple instances of the same rule active at the same time. This is useful when you want to enforce the same rule multiple times but with different options ([#113](https://github.com/jorisroovers/gitlint/issues/130), [#66](https://github.com/jorisroovers/gitlint/issues/130))
+- [User-defined Configuration Rules](http://jorisroovers.github.io/gitlint/user_defined_rules/#configuration-rules) allow users to dynamically change gitlint's configuration and/or the commit *before* any other rules are applied.
+- The `commit-msg` hook has been re-written in Python (it contained a lot of Bash before), fixing a number of platform specific issues. Existing users will need to reinstall their hooks (`gitlint uninstall-hook; gitlint install-hook`) to make use of this.
+- Most general options can now be set through environment variables (e.g. set the `general.ignore` option via `GITLINT_IGNORE=T1,T2`). The list of available environment variables can be found in the [configuration documentation](http://jorisroovers.github.io/gitlint/configuration).
+- Users can now use `self.log.debug("my message")` for debugging purposes in their user-defined rules. Debug messages will show up when running `gitlint --debug`.
+- **Breaking**: User-defined rule id's can no longer start with 'I', as those are reserved for [built-in gitlint ignore rules](http://jorisroovers.github.io/gitlint/rules/#i1-ignore-by-title).
+-  New `RegexOption` rule [option type for use in user-defined rules](http://jorisroovers.github.io/gitlint/user_defined_rules/#options). By using the `RegexOption`, regular expressions are pre-validated at gitlint startup and compiled only once which is much more efficient when linting multiple commits.
 - Bugfixes:
-  -  Options can now actually be set to `None` (from code) to make them optional.
-  -  Ignore rules no longer have "None" as default regex, but an empty regex - effectively disabling them by default (as intended).
--  New `RegexOption` rule option type for use in user-defined rules. By using the `RegexOption`, regular expressions are pre-validated at gitlint startup and compiled only once which is much more efficient compared when linting multiple commits.
-- Minor performance improvement: Removed some unneccessary regex matching
+  -  Improved UTF-8 fallback on Windows (ongoing - [#96](https://github.com/jorisroovers/gitlint/issues/96))
+  - Windows users can now use the 'edit' function of the `commit-msg` hook ([#94](https://github.com/jorisroovers/gitlint/issues/94))
+  -  Doc update: Users should use `--ulimit nofile=1024` when invoking gitlint using Docker ([#129](https://github.com/jorisroovers/gitlint/issues/129))
+  - The `commit-msg` hook was broken in Ubuntu's gitlint package due to a python/python3 mismatch ([#127](https://github.com/jorisroovers/gitlint/issues/127))
+  - Better error message when no git username is set ([#149](https://github.com/jorisroovers/gitlint/issues/149))
+  - Options can now actually be set to `None` (from code) to make them optional.
+  -  Ignore rules no longer have `"None"` as default regex, but an empty regex - effectively disabling them by default (as intended).
+- Contrib Rules:
+  - Added 'ci' and 'build' to conventional commit types ([#135](https://github.com/jorisroovers/gitlint/issues/135))
+- Under-the-hood: minor performance improvements (removed some unnecessary regex matching), test improvements, improved debug logging, CI runs on pull requests, PR request template.
 
 ## v0.13.1 (2020-02-26)
 

README.md

@@ -13,7 +13,7 @@ Git commit message linter written in python (for Linux and Mac, experimental on
 ## Contributing ##
 All contributions are welcome and very much appreciated!
 
-**I'm looking for contributors that are interested in taking a more active co-maintainer role as it's becoming increasingly difficult for me to find time to maintain gitlint. Please open a PR if you're interested - Thanks!**
+**I'm [looking for contributors](https://github.com/jorisroovers/gitlint/issues/134) that are interested in taking a more active co-maintainer role as it's becoming increasingly difficult for me to find time to maintain gitlint. Please open a PR if you're interested - Thanks!**
 
 See [jorisroovers.github.io/gitlint/contributing](http://jorisroovers.github.io/gitlint/contributing) for details on
 how to get started - it's easy!

docs/configuration.md

@@ -25,7 +25,7 @@ The block below shows a sample `.gitlint` file. Details about rule config option
 # one rule and each key in it is an option for that specific rule.
 #
 # Rules and sections can be referenced by their full name or by id. For example
-# section "[body-max-line-length]" could be written as "[B1]". Full section names are
+# section "[body-max-line-length]" could also be written as "[B1]". Full section names are
 # used in here for clarity.
 # Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/
 #
@@ -70,8 +70,8 @@ line-length=80
 
 # Conversely, you can also enforce minimal length of a title with the
 # "title-min-length" rule:
-# [title-min-length]
-# min-length=5
+[title-min-length]
+min-length=5
 
 [title-must-not-contain-word]
 # Comma-separated list of words that should not occur in the title. Matching is case
@@ -112,7 +112,7 @@ regex=My-Commit-Tag: foo$
 [author-valid-email]
 # python like regex (https://docs.python.org/2/library/re.html) that the
 # commit author email address should be matched to
-# For example, use the following regex if you only want to allow email addresses from foo.com
+# E.g.: For example, use the following regex if you only want to allow email addresses from foo.com
 regex=[^@][email protected]
 
 [ignore-by-title]
@@ -237,82 +237,6 @@ GITLINT_VERBOSITY=2 gitlint    # using env variable
 verbosity=2
 ```
 
-### ignore-merge-commits
-
-Whether or not to ignore merge commits.
-
-Default value  |  gitlint version | commandline flag  | environment variable  
----------------|------------------|-------------------|-----------------------
- true          | >= 0.7.0         | Not Available     | Not Available  
-
-#### Examples
-```sh
-# CLI
-gitlint -c general.ignore-merge-commits=false
-```
-```ini
-#.gitlint
-[general]
-ignore-merge-commits=false
-```
-
-### ignore-revert-commits
-
-Whether or not to ignore revert commits.
-
-Default value  |  gitlint version | commandline flag  | environment variable   
----------------|------------------|-------------------|-----------------------
- true          | >= 0.13.0        | Not Available     | Not Available  
-
-#### Examples
-```sh
-# CLI
-gitlint -c general.ignore-revert-commits=false
-```
-```ini
-#.gitlint
-[general]
-ignore-revert-commits=false
-```
-
-### ignore-fixup-commits
-
-Whether or not to ignore [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits.
-
-Default value  |  gitlint version | commandline flag  | environment variable  
----------------|------------------|-------------------|-----------------------
- true          | >= 0.9.0         | Not Available     | Not Available  
-
-#### Examples
-```sh
-# CLI
-gitlint -c general.ignore-fixup-commits=false
-```
-```ini
-#.gitlint
-[general]
-ignore-fixup-commits=false
-```
-
-### ignore-squash-commits
-
-Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits.
-
-Default value  |  gitlint version | commandline flag  | environment variable 
----------------|------------------|-------------------|-----------------------
- true          | >= 0.9.0         | Not Available     | Not Available  
-
-#### Examples
-```sh
-# CLI
-gitlint -c general.ignore-squash-commits=false
-```
-```ini
-#.gitlint
-[general]
-ignore-squash-commits=false
-```
-
 ### ignore
 
 Comma separated list of rules to ignore (by name or id).
@@ -414,6 +338,28 @@ GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint     # using env v
 [general]
 contrib=contrib-title-conventional-commits,CC1
 ```
+
+### staged
+
+Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or `--commit-msg`.
+
+Default value  |  gitlint version | commandline flag  | environment variable   
+---------------|------------------|-------------------|-----------------------
+ false         | >= 0.13.0        | `--staged`        | `GITLINT_STAGED`
+
+#### Examples
+```sh
+# CLI
+gitlint --staged
+gitlint -c general.staged=true # different way of doing the same
+GITLINT_STAGED=1 gitlint       # using env variable
+```
+```ini
+#.gitlint
+[general]
+staged=true
+```
+
 ### ignore-stdin
 
 Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
@@ -435,23 +381,78 @@ GITLINT_IGNORE_STDIN=1 gitlint       # using env variable
 ignore-stdin=true
 ```
 
-### staged
+### ignore-merge-commits
 
-Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or `--commit-msg`.
+Whether or not to ignore merge commits.
+
+Default value  |  gitlint version | commandline flag  | environment variable  
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.7.0         | Not Available     | Not Available  
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-merge-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-merge-commits=false
+```
+
+### ignore-revert-commits
+
+Whether or not to ignore revert commits.
 
 Default value  |  gitlint version | commandline flag  | environment variable   
 ---------------|------------------|-------------------|-----------------------
- false         | >= 0.13.0        | `--staged`        | `GITLINT_STAGED`
+ true          | >= 0.13.0        | Not Available     | Not Available  
 
 #### Examples
 ```sh
 # CLI
-gitlint --staged
-gitlint -c general.staged=true # different way of doing the same
-GITLINT_STAGED=1 gitlint       # using env variable
+gitlint -c general.ignore-revert-commits=false
 ```
 ```ini
 #.gitlint
 [general]
-staged=true
+ignore-revert-commits=false
 ```
+
+### ignore-fixup-commits
+
+Whether or not to ignore [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits.
+
+Default value  |  gitlint version | commandline flag  | environment variable  
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.9.0         | Not Available     | Not Available  
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-fixup-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-fixup-commits=false
+```
+
+### ignore-squash-commits
+
+Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits.
+
+Default value  |  gitlint version | commandline flag  | environment variable 
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.9.0         | Not Available     | Not Available  
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-squash-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-squash-commits=false
+```

docs/contributing.md

@@ -13,13 +13,13 @@ that's open to a lot of change and input.
 
 When contributing code, please consider all the parts that are typically required:
 
-- [Unit tests](https://github.com/jorisroovers/gitlint/tree/master/gitlint/tests) (automatically
+- [Unit tests](https://github.com/jorisroovers/gitlint/tree/main/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
+- [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/master/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
@@ -63,12 +63,12 @@ To run tests:
 ./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.
+The `Vagrantfile` comes with `virtualenv`s for python 2.7, 3.5, 3.6, 3.7, 3.8, 3.9 and pypy2.
 You can easily run tests against specific python environments by using the following commands *inside* of the Vagrant VM:
 ```sh
 ./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 27,37,pypy2      # Run the unit tests against Python 2.7, Python 3.7 and Pypy2
+./run_tests.sh --envs 27,37 --pep8     # Run pep8 checks against Python 2.7 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
 ```
@@ -115,9 +115,9 @@ 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/rules).
-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.
+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/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/tests/contrib/rules).
+4. **Write documentation**. In particular, you should update the [gitlint/docs/contrib_rules.md](https://github.com/jorisroovers/gitlint/blob/main/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!
 
 

docs/index.md

@@ -247,7 +247,7 @@ future versions of gitlint might fix this and not require the `--pretty` argumen
 
 _Introduced in gitlint v0.9.0 (experimental in v0.8.0)_
 
-Gitlint allows users to commit a number of commits at once like so:
+Gitlint allows users to lint a number of commits at once like so:
 
 ```sh
 # Lint a specific commit range:
@@ -261,10 +261,8 @@ gitlint --commits "019cf40^...019cf40"
 The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood
 by [git rev-list](https://git-scm.com/docs/git-rev-list) as a single argument will work.
 
-Prior to v0.8.1 gitlint didn't support this feature. However, older versions of gitlint can still lint a range or set
-of commits at once by creating a simple bash script that pipes the commit messages one by one into gitlint. This
-approach can still be used with newer versions of gitlint in case `--commits` doesn't provide the flexibility you
-are looking for.
+For cases where the `--commits` option doesn't provide the flexibility you need, you can always use a simple shell
+script to lint an arbitrary set of commits, like shown in the example below.
 
 ```sh
 #!/bin/sh
@@ -403,15 +401,15 @@ $ gitlint
 
 Named rules are further treated identical to all other rules in gitlint:
 
-- you can reference by their full name, when e.g. adding them to your `ignore` configuration
+- You can reference them by their full name, when e.g. adding them to your `ignore` configuration
 ```ini
 # .gitlint file example
 [general]
 ignore=T5:more-words,title-must-not-contain-word:extra-words
 ```
 
-- you can use them to instantiate multiple of the same [user-defined rule](user_defined_rules.md)
-- you can configure them using [any of the ways you can configure regular gitlint rules](configuration.md)
+- You can use them to instantiate multiple of the same [user-defined rule](user_defined_rules.md)
+- You can configure them using [any of the ways you can configure regular gitlint rules](configuration.md)
 
 
 ## Exit codes