Documentation improvements

Made some documentation updates with the sight on the upcoming 0.8.0
release.
Also brought the CHANGELOG up-to-date.

CHANGELOG.md

@@ -1,9 +1,16 @@
 # Changelog #
 
-## v0.8.0 (In Development) ##
+## v0.8.0 (2016-12-30) ##
+
+The 0.8.0 release is a significant release that has been in the works for a long time. Special thanks to
+[Claymore](https://github.com/Claymore), [gernd](https://github.com/gernd) and
+[ZhangYaxu](https://github.com/ZhangYaxu) for submitting bug reports and pull requests.
 
 - Full unicode support: you can now lint messages in any language! This fixes
   [#16](https://github.com/jorisroovers/gitlint/issues/16) and [#18](https://github.com/jorisroovers/gitlint/pull/18).
+- User-defined rules: you can now
+  [define your own custom rules](http://jorisroovers.github.io/gitlint/user_defined_rules/)
+  if you want to extend gitlint's functionality.
 - Pypy2 support!
 - Debug output improvements: Gitlint will now print your active configuration when using ```--debug```
 - The ```general.target``` option can now also be set via ```-c``` flags or a ```.gitlint``` file
@@ -12,12 +19,12 @@
     - [#17: Body MinLength is not working properly](https://github.com/jorisroovers/gitlint/issues/17).
       **Behavior Change**: Gitlint now always applies this rule, even if the body has just a single line of content.
       Also, gitlint now counts the body-length for the entire body, not just the length of the first line.
+- Various documentation improvements
 - Development: 
     - Pylint compliance for all supported python versions
     - Updated dependencies to latest versions
     - Various ```run_tests.sh``` improvements for developer convenience
 
-
 ## v0.7.1 (2016-06-18) ##
 Bugfixes:
 

README.md

@@ -1,4 +1,4 @@
-# gitlint #
+# gitlint: [jorisroovers.github.io/gitlint](http://jorisroovers.github.io/gitlint/) #
 
 [![Build Status](https://travis-ci.org/jorisroovers/gitlint.svg?branch=master)]
 (https://travis-ci.org/jorisroovers/gitlint)

docs/configuration.md

@@ -90,7 +90,7 @@ gitlint-ignore: all
 specific rules to be ignored as follows: ```gitlint-ignore: T1, body-hard-tab```.
 
 # Configuration precedence #
-Configuring gitlint happens the following order of precedence:
+gitlint configuration is applied in the following order of precedence:
 
 1. Commit specific config (e.g.: ```gitlint-ignore: all``` in the commit message) 
 2. Commandline convenience flags (e.g.:  ```-vv```, ```--silent```, ```--ignore```)
@@ -109,4 +109,5 @@ verbosity            | 3             | >= 0.1           | ```--verbosity=3```
 ignore-merge-commits | true          | >= 0.7.0         |   Not available                       | Whether or not to ignore merge commits.
 ignore               | [] (=empty)   | >= 0.1           | ```--ignore=T1,body-min-length```     | Comma seperated list of rules to ignore (by name or id)
 debug                | false         | >= 0.7.1         |  ```--debug```                        | Enable debugging output
-extra-path           | (empty)       | >= 0.8.0         |  ```---extra-path=/home/joe/rules/``` | Path where gitlint looks for [user-defined rules](user_defined_rules.md).
+target               | (empty)       | >= 0.8.0         |  ```---target=/home/joe/myrepo/   ``` | Target git repository gitlint should be linting against.
+extra-path           | (empty)       | >= 0.8.0         |  ```---extra-path=/home/joe/rules/``` | Path where gitlint looks for [user-defined rules](user_defined_rules.md).

docs/contributing.md

@@ -25,23 +25,27 @@ To run tests:
 ./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 --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
-./run_tests.sh --lint                # run pylint checks (only supported on python 2.7)
 ```
 
-The ```Vagrantfile``` comes with ```virtualenv```s for python 2.6, 2.7, 3.3, 3.4 and 3.5.
+The ```Vagrantfile``` comes with ```virtualenv```s for python 2.6, 2.7, 3.3, 3.4, 3.5 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 26               # Run the unit tests against Python 2.6
-./run_tests.sh --envs 27,33            # Run the unit tests against Python 2.7 and Python 3.3
+./run_tests.sh --envs 27,33,pypy2      # Run the unit tests against Python 2.7, Python 3.3 and Pypy2
 ./run_tests.sh --envs 27,33 --pep8     # Run pep8 checks against Python 2.7 and Python 3.3 (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

docs/index.md

@@ -11,17 +11,19 @@ Great for use as a ```commit-msg``` git hook or as part of your gating script in
     [node-commit-msg](https://github.com/clns/node-commit-msg) (Node.js).
 
 ## Features ##
- - **Commit message hook**: Auto-trigger validations against new commit message right when you're committing.
- - **Easily integrated**: Gitlint will validate any git commit message you give it via standard input. Perfect for integration with your own scripts or CI system.
+ - **Commit message hook**: [Auto-trigger validations against new commit message right when you're committing](#using-gitlint-as-a-commit-msg-hook).
+ - **Easily integrated**: Gitlint will validate any git commit message you give it via standard input.
+   Perfect for [integration with your own scripts or CI system](#using-gitlint-in-a-cicd-script).
  - **Sane defaults:** Many of gitlint's validations are based on
 [well-known](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
 [community](http://addamhardy.com/blog/2013/06/05/good-commit-messages-and-enforcing-them-with-git-hooks/),
 [standards](http://chris.beams.io/posts/git-commit/), others are based on checks that we've found
 useful throughout the years.
  - **Easily configurable:** Gitlint has sane defaults, but [you can also easily customize it to your own liking](configuration.md).
- - **User-defined Rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules).
+ - **User-defined Rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules.md).
  - **Broad python version support:** Gitlint supports python versions 2.6, 2.7, 3.3+ and PyPy2.
- - **Production-ready:** Gitlint checks a lot of boxes you're looking for: high unit test coverage, integration tests,
+ - **Full unicode support:** Lint your Russian, Chinese or Emoji commit messages with ease!
+ - **Production-ready:** Gitlint checks a lot of the boxes you're looking for: high unit test coverage, integration tests,
    python code standards (pep8, pylint), good documentation, proven track record.
 
 ## Getting Started ##
@@ -114,6 +116,8 @@ Commands:
 
 
 ## Using gitlint as a commit-msg hook ##
+_Introduced in gitlint v0.4.0_
+
 You can also install gitlint as a git ```commit-msg``` hook so that gitlint checks your commit messages automatically
 after each commit.
 
@@ -129,8 +133,52 @@ gitlint uninstall-hook
     file in your local repository, gitlint will refuse to install the ```commit-msg``` hook. Gitlint will also only
     uninstall unmodified commit-msg hooks that were installed by gitlint.
 
+## Using gitlint in a CI/CD script ##
+By default, when just running ```gitlint``` without additional parameters, gitlint lint the last commit in the current
+git repository.
+
+This makes it easy to add gitlint to a check script that is run in a CI environment. In fact, this is exactly what we
+do ourselves: on every commit,
+[we run gitlint as part of our travisCI tests](https://github.com/jorisroovers/gitlint/blob/v0.7.1/run_tests.sh#L62-L65).
+This will cause the build to fail when we submit a bad commit message.
+
+Gitlint will also lint any commit message that you feed it via stdin like so:
+```bash
+# lint the last commit message
+git log -1 --pretty=%B | gitlint
+# lint a specific commit: 62c0519
+git log -1 --pretty=%B 62c0519 | gitlint
+```
+For now, it's required that you specify ```--pretty=%B``` (=only print the log message, not the metadata),
+future versions of gitlint might fix this.
+
+### Linting a range of commits ###
+
+While gitlint does not yet support linting a range or set of commits at once, it's actually quite easy to do this using
+a simple bash script that pipes the commit messages one by one into gitlint.
+
+```bash
+#!/bin/bash
+
+for commit in $(git rev-list master); do
+    commit_msg=$(git log -1 --pretty=%B $commit)
+    echo "$commit"
+    echo "$commit_msg" | gitlint
+    echo "--------"
+done
+```
+!!! note
+    One downside to this approach is that you invoke gitlint once per commit vs. once per set of commits.
+    This means you'll incur the gitlint startup time once per commit, making this approach rather slow if you want to
+    lint a large set of commits. For reference, at the time of writing, linting gitlint's entire commit log
+    (~160 commits) this way took about 40 seconds on a 2015 Macbook Pro. Linting the entire commit log of git
+    itself (~45,500 commits) took 2hr and 50 mins.
+
+
 ## Merge commits ##
-As of version 0.7.0, gitlint ignores merge commits by default. The rationale behind this is that in many cases
+_Introduced in gitlint v0.7.0_
+
+Gitlint ignores merge commits by default. The rationale behind this is that in many cases
 merge commits are not created by users themselves but by tools such as github,
 [gerrit](https://code.google.com/p/gerrit/) and others. These tools often generate merge commit messages that
 violate gitlint's set of rules and it's not always convenient or desired to change those.

docs/rules.md

@@ -1,5 +1,10 @@
 # Overview #
 
+The table below shows an overview of all gitlint's built-in rules.
+Note that you can also [write your own user-defined rule](user_defined_rules.md) in case you don't find
+what you're looking for.
+The rest of this page contains details on the available configuration options for each built-in rule.
+
 ID    | Name                        | gitlint version | Description
 ------|-----------------------------|---------------- |-------------------------------------------
 T1    | title-max-length            | >= 0.1          | Title length must be < 72 chars.

docs/user_defined_rules.md

@@ -1,5 +1,5 @@
 # User Defined Rules
-*New in gitlint 0.8.0*
+_Introduced in gitlint v0.8.0_
 
 Gitlint supports the concept of user-defined rules: the ability for users
 to write your own custom rules that are executed when gitlint is.