Merge pull request #14 from devlinjunker/release-0.2

release-0.2

.github/workflows/README.md

@@ -25,6 +25,8 @@ This directory contains files related to Github configurations and actions:
   - Runs the verify-merge.sh script in `scripts/` directory and fails the action if the script does not complete succesfully
     - Prevents mergin branches with name `poc` or where last commit contains `wip` 
   - Verifies that Pull Request Title matches branch prefix
+  - Runs BATS tests and errors if they fail
+  - Lints the shell script files with Shellcheck
 
   ### Cut `release-*` Branch Action (release-cut.yaml)
   - Verifies `feature` commits have been added to `develop` since last release cut
@@ -34,6 +36,8 @@ This directory contains files related to Github configurations and actions:
   ### Verify `main` Merge Action (main-verify-merge.yaml)
   - Verifies that Pull Request Title is correct format `release-*` or `hotfix-*`
   - Verifies that Pull Request branch is `release-*` or `hotfix-*` branch
+  - Runs BATS tests and errors if they fail
+  - Lints the shell script files with Shellcheck
 
   ### On Merge to `main` Action (main-on-merge.yaml)
   - Syncs README.md files to wiki

.github/workflows/develop-verify-merge.yaml

@@ -15,6 +15,8 @@ jobs:
     steps:
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
     - uses: actions/checkout@v2
+      with:
+        submodules: 'recursive'
 
     - name: Prevent POC/WIP branches
       run: |
@@ -34,4 +36,10 @@ jobs:
       with:
         regex: '(\([\w\s]*\)*\))?:[\w\s]*'
         allowed_prefixes:  ${{ steps.extract_branch.outputs.prefix }}
-        prefix_case_sensitive: true
+        prefix_case_sensitive: true
+
+    - name: "Verify BATS Tests Pass"
+      run: 'scripts/bin/test.sh'
+
+    - name: "Lint with Shellcheck"
+      run: 'scripts/bin/lint.sh'

.github/workflows/main-verify-merge.yaml

@@ -13,6 +13,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v2
+      with:
+        submodules: 'recursive'
 
     - name: "Verify 'main' PR are from 'release-*' or 'patch-*' branch"
       run: ./scripts/workflows/branch-match.sh
@@ -24,4 +26,10 @@ jobs:
       uses: deepakputhraya/action-pr-title@master
       with:
         regex: '-[0-9]+.[0-9]+(.[0-9]+)?'
-        allowed_prefixes:  release,patch
+        allowed_prefixes:  release,patch
+
+    - name: "Verify BATS Tests Pass"
+      run: 'scripts/bin/test.sh'
+
+    - name: "Lint with Shellcheck"
+      run: 'scripts/bin/lint.sh'

.gitmodules

@@ -0,0 +1,9 @@
+[submodule "lib/bats-core"]
+	path = lib/bats-core
+	url = https://github.com/bats-core/bats-core
+[submodule "lib/bats-assert"]
+	path = lib/bats-assert
+	url = https://github.com/bats-core/bats-assert
+[submodule "lib/bats-support"]
+	path = lib/bats-support
+	url = https://github.com/bats-core/bats-support

CONTRIBUTING.md

@@ -11,10 +11,10 @@ The best way to [report an issue is through Github](https://github.com/devlinjun
 <!-- This section details the steps to setup the project for development -->
 
 ### Environment Setup and Tools
-You will need to install Git and create an account on Github to take advantage of all of the features of this template. This template also uses scripts that expect Bash to be installed at `/bin/bash`.
+This example uses scripts that expect Bash to be installed at `/bin/bash`. The rest of the tools should be included when you clone the repo.
 
-#### Create your own Project from this Template
-There are multiple ways to use this template as a starting point for your own project. The **best way to use this is by cloning the repo to your GitHub account and creating your project with the template feature provided by Github**:
+#### Create your own Project from this Example
+There are multiple ways to use this example as a starting point for your own project. The **best way to use this is by cloning the repo to your GitHub account and creating your project with the template feature provided by Github**:
 
 <img width="1130" alt="template" src="https://user-images.githubusercontent.com/1504590/95393957-55b31c80-08b0-11eb-9126-55d8105881f4.png">
 
@@ -52,8 +52,8 @@ git push --set-upstream origin develop
 Once you have a framework and development environment chosen for your project, you should update your repo with specifics about how to install the tools and dependencies needed to run/debug/develop the application (See README for checklist).
 
 
-#### Update a Project or add to existing Project
-The steps **to update a Project that was created using this template**, or to **add these features to an existing project** are the same. In the projects root directory:
+#### Add Bash Testing to your Project
+You can also **add these features to an existing project** by using this template and following these steps:
 ```
 git checkout main;
 git remote add template https://github.com/devlinjunker/example.cii.git;
@@ -67,6 +67,8 @@ git commit;
 git push;
 ```
 
+**Or you can just use this example as an idea for your own projects**
+
 
 ### Folder Structure
 Break down how each folder is used in the repo and how different code file types should be organized.
@@ -78,9 +80,13 @@ Break down how each folder is used in the repo and how different code file types
 |-- workflows/
 |---- (Github workflow .yaml files)
 |-- (other github specific files)
-- img/
-|-- (project image files)
+- qa/
+|-- scripts/
+|---- files specific to testing the script files (BATS)
+|-- (other testing files should be stored in here)
 - scripts/
+|-- bin/
+|---- (Scripts for developers to run the project)
 |-- hooks/
 |---- (Git Hooks Scripts)
 |-- release/
@@ -134,24 +140,30 @@ Review the [Security Policy](https://github.com/devlinjunker/template.github.sem
 
 
 #### Style Guide
-Once you start your project, you should update the style guide here or [link to a Wiki page](https://github.com/devlinjunker/template.github.semver/wiki/Styleguide) from here.
+This example uses the [Shellcheck](https://www.shellcheck.net/) command line tool to ensure that the Bash Scripts that help automate the Semantic Versioning process are written with up to date standards.
+
+See the [Shellcheck Wiki](https://github.com/koalaman/shellcheck/wiki/Checks) for a full list of the checks that it is performing
 
-Some ideas of things to include in your styleguide include:
- - Code Formating and (linting) tools used to ensure the style is met
- - Organization of Files
- - Best practices for designing new features
+Run the linting process with:
+```
+scripts/bin/lint.sh
+```
 
 
 #### Testing
-This template doesn't include any tests yet (although we could add them...). Once you start using this for your own project though, you should include any testing details and requirements here.
-
-Ideas to consider for testing:
- - unit tests
- - integration tess
- - e2e tests
- - automation tests
- - contract tests
- - mutation tests
+This example includes tests for each of the Bash Scripts that help automate the Semantic Versioning process in GitHub Actions and that run during the Git Hooks. Each `.sh` file in the `scripts/` directory should have a corresponding `.bats` file in the `qa/scripts/` directory.
+
+Run every test with:
+```
+qa/runner.sh
+```
+
+Run a single test with:
+```
+qa/runner.sh --file <path to file>
+```
+
+See the [READMEs in `qa/` directory](https://github.com/devlinjunker/example.cii/tree/develop/qa)
 
 
 #### Release 

README.md

@@ -1,5 +1,5 @@
 ---
-Version: 0.1.0
+Version: 0.2.0
 ---
 
 # Example - CII 100%
@@ -8,31 +8,28 @@ Version: 0.1.0
 [![GitHub License](https://img.shields.io/github/license/devlinjunker/example.cii?color=blue)](https://github.com/devlinjunker/example.cii/blob/develop/LICENSE)  
 [![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/devlinjunker/example.cii)](https://github.com/devlinjunker/example.cii/releases)
 [![GitHub last commit](https://img.shields.io/github/last-commit/devlinjunker/example.cii)](https://github.com/devlinjunker/example.cii/commits/main)  
-<!-- [![CII Best Practices Summary](https://img.shields.io/cii/summary/4287?label=core-infrastructure)](https://bestpractices.coreinfrastructure.org/en/projects/4287)  -->
+[![CII Best Practices Summary](https://img.shields.io/cii/summary/4558?label=core-infrastructure)](https://bestpractices.coreinfrastructure.org/en/projects/4558)  
 [![GitHub issues](https://img.shields.io/github/issues/devlinjunker/example.cii)](https://github.com/devlinjunker/example.cii/issues)
 [![GitHub priority issues](https://img.shields.io/github/issues/devlinjunker/example.cii/-priority?color=red&label=priority%20issues)](https://github.com/devlinjunker/example.cii/issues?q=is%3Aopen+is%3Aissue+label%3A-priority)
 
 
 ## Intro
 <!-- Quick Description, could match Github repo description or have a little more info-->
 
-This is an example project with a goal of 100% Passing [Core Infrastructure Initiative Criteria]. 
+This is an example project with a goal of 100% passing [Core Infrastructure Initiative Criteria] status. It is based off of the [Github Semver Project](https://github.com/devlinjunker/template.github.semver) Template. 
 
-It is based off of:
-- Template [Github Semver Project](https://github.com/devlinjunker/template.github.semver)
-
-<!-- 
-With improvements:
+Contains the following improvements for passing status:
+- Automated Test Suite (for Bash Scripts)
 - Static Code Analysis (Linting)
-- Automated Test Suite
--->
 
 
 ## Dependencies/Frameworks
 <!-- List the frameworks, libraries, and tools the project uses: -->
 
 - [Bulldozer] - Github Application to Auto Squash and Merge feature PRs
 - [Git-mkver] - Binary that helps with determining next semantic version based on Git Tags
+- [BATS] - Automated Test Suite for Bash Scripts
+- [ShellCheck] - Linting Tool for Bash Scripts
 
 ## Quick Setup/Run
 <!-- This section should try to quickly explain how to setup the project and start using it (server/app/demo/template) - ideally in list format -->
@@ -45,7 +42,7 @@ With improvements:
  - [ ] Update this README and Links with project specific details
  - [ ] Review [Github Workflows] in Template (and improve for your process)
  - [ ] Add Custom Project Build and Configuration Files
- - Start Coding!
+ - Start Writing Tests and Coding!
 
 ## Links
 
@@ -72,4 +69,6 @@ With improvements:
 [Bash]: https://tldp.org/LDP/abs/html/
 [Github Actions]: https://docs.github.com/en/free-pro-team@latest/actions
 [Bulldozer]: https://github.com/palantir/bulldozer
-[Git-mkver]: https://idc101.github.io/git-mkver/
+[Git-mkver]: https://idc101.github.io/git-mkver/
+[BATS]: https://bats-core.readthedocs.io/
+[ShellCheck]: https://www.shellcheck.net/

SECURITY.md

@@ -10,10 +10,7 @@ currently being supported with security updates -->
 
 | Version | Supported          |
 | ------- | ------------------ |
-| > 1.0.x | :white_check_mark: |
-| > 0.12.x | :white_check_mark: |
-|  0.11.x  | :heavy_minus_sign: |
-| < 0.10   | :x:                |
+| > 0.1.x | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

lib/.gitignore

@@ -0,0 +1 @@
+shellcheck*/

qa/README.md

@@ -0,0 +1,22 @@
+# Testing
+
+The `qa/` directory contains files used during testing. It is named "qa" so that it will precede the `script/` and `src/` directories that it will be testing in Pull Requests.
+
+Each feature that is added to this project should include test files that detail the expectations for the new feature. If there is a new unit testing framework needed, please [submit an issue](https://github.com/devlinjunker/example.cii/issues/new/choose).
+
+For now this includes:
+ - unit tests with BATS for script files
+
+## Test Running Script
+The `scripts/bin/` directory also contains a script file (`test.sh`) that manages running all of the test files. This will either:
+ - run all tests if no arguments are passed (or `-a/--all`)
+ - or will try to find a specific file to run with the `-f/--file` argument
+
+## Other Ideas
+ - integration tests
+ - e2e tests
+ - automation tests
+ - contract tests
+ - mutation tests
+ - helpers?
+    - BATS helper - mocking/stubbing/spying (see [here](scripts/release/release-prep-upmerge.bats))

qa/scripts/README.md

@@ -0,0 +1,17 @@
+## Testing Script Files
+
+Shell Script testing is done with [BATS]. These tests are organized in the same structure as the `script/` file directory and test files will have the same name as the script they are testing.
+
+
+To run every BATS test:
+```
+lib/bats-core/bin/bats qa -r
+```
+
+To run a single BATS test:
+```
+lib/bats-core/bin/bats <path to .bats file>
+```
+
+
+[BATS]: https://bats-core.readthedocs.io/

qa/scripts/hooks/branch-name.bats

@@ -0,0 +1,68 @@
+#!/usr/bin/env ../../..libs/bats/bin/bats
+load '../../../lib/bats-support/load'
+load '../../../lib/bats-assert/load'
+
+SCRIPT_DIR="$BATS_TEST_DIRNAME"/../../../scripts/hooks
+
+TEST_PREFIX="branch-name.sh -";
+
+
+@test "$TEST_PREFIX should not allow branches that don't match output of prefix-list.sh or defaults" {
+    function git() {
+        echo "abc/test-name";
+    }
+    export -f git
+
+    BATS_PREFIX_LIST=""
+    export BATS_PREFIX_LIST
+
+    run "$SCRIPT_DIR"/branch-name.sh
+    unset BATS_PREFIX_LIST
+
+    assert_failure
+}
+
+@test "$TEST_PREFIX should allow default branch prefixes (feat, fix)" {
+    function git() {
+        echo "fix/test-name";
+    }
+    export -f git
+
+    run "$SCRIPT_DIR"/branch-name.sh
+
+    assert_success
+
+    function git() {
+        echo "feat/test-name";
+    }
+    export -f git
+
+    run "$SCRIPT_DIR"/branch-name.sh
+
+    assert_success
+}
+
+@test "$TEST_PREFIX should allow branches that match output of prefix-list.sh" {
+    function git() {
+        echo "abc/test-name";
+    }
+    export -f git
+
+    BATS_PREFIX_LIST="abc"
+    export BATS_PREFIX_LIST
+
+    run "$SCRIPT_DIR"/branch-name.sh
+    unset BATS_PREFIX_LIST
+
+    assert_success
+}
+
+@test "$TEST_PREFIX should allow patch branches" {
+    function git() {
+        echo "patch-0.0.1"
+    }
+    export -f git
+
+    run "$SCRIPT_DIR"/branch-name.sh
+    assert_success
+}