From bc90a848f54fae4f42464a163cb197347c38ddcc Mon Sep 17 00:00:00 2001
From: Dylan Araps <dylan.araps@gmail.com>
Date: Fri, 15 Jun 2018 10:46:54 +1000
Subject: [PATCH] run shellcheck in the test script

---
 .travis.yml     |  1 -
 CONTRIBUTING.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 test.sh         |  8 +++++-
 3 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/.travis.yml b/.travis.yml
index 55c10f2..830bf11 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -4,5 +4,4 @@ os:
     - linux
 
 script:
-    - shellcheck -s bash --exclude=SC2034,SC2154 <(awk '/```sh$/{f=1;next}/```/{f=0}f' README.md)
     - ./test.sh
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..724f01f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,76 @@
+# Writing the Bible
+
+<!-- vim-markdown-toc GFM -->
+
+* [Adding Code to the Bible.](#adding-code-to-the-bible)
+* [Special meanings for code blocks.](#special-meanings-for-code-blocks)
+* [Writing tests](#writing-tests)
+* [Running the tests](#running-the-tests)
+
+<!-- vim-markdown-toc -->
+
+## Adding Code to the Bible.
+
+- The code must use only `bash` built-ins.
+    - A fallback to an external program is allowed if the code doesn't
+      always work.
+    - Example Fallback: `${HOSTNAME:-$(hostname)}`
+- If possible, wrap the code in a function.
+    - This allows tests to be written.
+    - It also allows `shellcheck` to properly lint it.
+    - An added bonus is showing a working use-case.
+- Write some examples.
+    - Show some input and the modified output.
+
+
+## Special meanings for code blocks.
+
+Use `sh` for functions that should be linted and unit tested.
+
+    ```sh
+    # Shellcheck will lint this and the test script will source this.
+    func() {
+        # Usage: func "arg"
+        :
+    }
+    ```
+
+Use `shell` for code that should be ignored.
+
+    ```shell
+    # Shorter file creation syntax.
+    :>file
+    ```
+
+## Writing tests
+
+The test file is viewable here: https://github.com/dylanaraps/pure-bash-bible/blob/master/test.sh
+
+Example test:
+
+```sh
+test_upper() {
+    result="$(upper "HeLlO")"
+    assert_equals "$result" "HELLO"
+}
+```
+
+Steps:
+
+1. Write the test.
+    - Naming is `test_func_name`
+    - Store the function output in a variable.
+    - Use `assert_equals` to test equality between the variable and the
+      expected output.
+2. ???
+3. The test script will automatically execute it. :+1:
+
+
+## Running the tests
+
+Running `test.sh` also runs `shellcheck` on the code.
+
+```sh
+cd pure-bash-bible
+./test.sh
+```
diff --git a/test.sh b/test.sh
index 7cb6d80..bd6f49f 100755
--- a/test.sh
+++ b/test.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# shellcheck source=/dev/null
 #
 # Tests for the Pure Bash Bible.
 
@@ -134,8 +135,12 @@ assert_equals() {
 }
 
 main() {
+    # Run shellcheck on the code.
+    awk '/```sh$/{f=1;next}/```/{f=0}f' README.md > readme_code
+    shellcheck -s bash --exclude=SC2034,SC2154 readme_code || exit 1
+
     # Get the code blocks from README.md
-    source <(awk '/```sh$/{f=1;next}/```/{f=0}f' README.md) 2>/dev/null
+    . readme_code
 
     head="-> Running tests on the Pure Bash Bible.."
     printf '\n%s\n%s\n' "$head" "${head//?/-}"
@@ -146,6 +151,7 @@ main() {
 
     comp="Completed ${#funcs[@]} tests. ${pass:-0} passed, ${err:-0} errored."
     printf '%s\n%s\n\n' "${comp//?/-}" "$comp"
+    rm readme_code
 
     # If a test failed, exit with '1'.
     [[ -f /tmp/err ]] || exit 0 && { rm /tmp/err; exit 1; }