From 1e69d542c16c2a32acfd139e32efa07a45f19111 Mon Sep 17 00:00:00 2001
From: Mario Nebl <marionebl@users.noreply.github.com>
Date: Thu, 4 May 2017 13:31:34 +0200
Subject: [PATCH] docs: add recipe for linting of all commits in a PR (#36)

* be more explicit / guide more than #24
* closes #35
* connected to #12
---
 readme.md               | 47 ++++++++++++++++++++++++++++++++++++-----
 scripts/lint:commits.sh | 12 ++++++-----
 2 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/readme.md b/readme.md
index 19b6baca20..fc80c6a3f7 100644
--- a/readme.md
+++ b/readme.md
@@ -67,16 +67,53 @@ As part of `npm test`
   }
 ```
 
+#### Lint all commits in Pull Request
+
+You can lint all commits in a PR by passing all commits that
+are present in `SOURCE_BRANCH` but unavailable in `BASE_BRANCH`:
+
+```sh
+conventional-changelog-lint --from=BASE_BRANCH to=SOURCE_BRANCH
+```
+
+Most of the time `BASE_BRANCH` will be `master` for Github Flow.
+
+This assumes `SOURCE_BRANCH` is available on your local checkout.
+This is not true by default for all PRs originating from clones of a repository.
+
+Given you'd like to lint all commits in PR origination from branch `remote-test` on the
+repository `github.com/other-name/test` targeting `master` on `github.com/your-name/test`:
+
+```sh
+cd test # make sure CWD is in your repository
+git remote add other-name https://github.com/other-name/test.git
+git fetch other-name
+
+conventional-changelog-lint --from=master --to=other-name/test
+```
+
+See [scripts/lint:commit.sh](./scripts/lint:commit.sh#6) for an example on how to obtain `SOURCE_BRANCH` from a Github clone automatically on Travis.
+
 #### Travis
 
+Commit Linting on CI has to handle the following cases
+
+* Direct commits
+* Branch Pull Requests
+* Fork Pull Requests
+
+An exemplary implementation is provided as bash script working on Travis CI.
+
 ```yml
 # Force full git checkout
 before_install: git fetch --unshallow
 
-# Lint all commits not in the target branch
-before_script: conventional-changelog-lint --from=$TRAVIS_BRANCH to=$TRAVIS_PULL_REQUEST_BRANCH
+script:
+  - ./scripts/lint:commit.sh # [1] scripts/lint:commit.sh
 ```
 
+> \[1\]: See [scripts/lint:commit.sh](./scripts/lint:commit.sh) for reference
+
 ### API
 
 The programming interface does not read configuration by default,
@@ -208,7 +245,7 @@ Perform `git fetch --shallow` before linting.
 Most likely you are reading this because you where presented with an error message:
 
 ```
-  'Could not get git history from shallow clone. 
+  'Could not get git history from shallow clone.
   Use git fetch --shallow before linting.
   Original issue: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'
 ```
@@ -217,7 +254,7 @@ Most likely you are reading this because you where presented with an error messa
 
 git supports checking out `shallow` clones of a repository to save bandwith in times.
 These limited copies do not contain a full git history. This makes `conventional-changelog-lint`
-fail, especially when running on large commit ranges. 
+fail, especially when running on large commit ranges.
 To ensure linting works every time you should convert a shallow git repo to a complete one.
 Use `git fetch --shallow` to do so.
 
@@ -226,7 +263,7 @@ Use `git fetch --shallow` to do so.
 Ensure full git checkouts on TravisCI, add to `.travis.yml`:
 
 ```yml
-before_install: 
+before_install:
   - git fetch --unshallow
 ```
 
diff --git a/scripts/lint:commits.sh b/scripts/lint:commits.sh
index 9772afa97a..a54d5cefab 100755
--- a/scripts/lint:commits.sh
+++ b/scripts/lint:commits.sh
@@ -2,21 +2,23 @@
 set -e
 set -u
 
-# Add the clone as remote if this is a PR from a clone
 if [[ $TRAVIS_PULL_REQUEST_SLUG != "" && $TRAVIS_PULL_REQUEST_SLUG != $TRAVIS_REPO_SLUG ]]; then
+	# This is a Pull Request from a different slug, hence a forked repository
 	git remote add "$TRAVIS_PULL_REQUEST_SLUG" "https://github.com/$TRAVIS_PULL_REQUEST_SLUG.git"
 	git fetch "$TRAVIS_PULL_REQUEST_SLUG"
-fi
 
-# Use REMOTE/BRANCH as comparison if applicable
-if [[ $TRAVIS_PULL_REQUEST_SLUG != "" ]]; then
+	# Use the fetched remote pointing to the source clone for comparison
 	TO="$TRAVIS_PULL_REQUEST_SLUG/$TRAVIS_PULL_REQUEST_BRANCH"
 else
-	TO="$TRAVIS_PULL_REQUEST_BRANCH"
+	# This is a Pull Request from the same remote, no clone repository
+	TO=$TRAVIS_COMMIT
 fi
 
 # Lint all commits in the PR
+# - Covers fork pull requests (when TO=slug/branch)
+# - Covers branch pull requests (when TO=branch)
 conventional-changelog-lint --from="$TRAVIS_BRANCH" --to="$TO"
 
 # Always lint the triggerig commit
+# - Covers direct commits
 conventional-changelog-lint --from="$TRAVIS_COMMIT"