Merge pull request #63 from github/UpdateDocs

adding them docs

.automation/README.md

@@ -11,9 +11,12 @@ This script uses **GitHub Actions** so that a push to the repository is committe
 - Build the **Docker** container for **Super-Linter** using that source code
 - Upload the container to **DockerHub**
 
-When the script is triggered on master, it will push with the tag:**latest** which is used by all scripting for general avilablity.
+When the script is triggered on master, it will push with the tag:**latest** which is used by all scripting for general availability.
 When the script is triggered in a branch, it will push with the tag:**NameOfBranch** which can be used for:
 - *testing*
 - *troubleshooting*
 - *debugging*
-- **Note:** The branch name will be reduced to AlpaNumeric for consistancy and uploading
+- **Note:** The branch name will be reduced to AlpaNumeric for consistency and uploading
+
+## test
+This folder holds all **Test Cases** to help run the *CI/CT/CD* process for the **Super-Linter**.

.automation/test/README.md

@@ -1,8 +1,15 @@
 # Test Cases
-This folder holds `template test cases` that are used to validate the sanity of the **Super-Linter**.
+This folder holds `test cases` that are used to validate the sanity of the **Super-Linter**.
 The format:
 - Each **Super-Linter** language should have its own folder
   - Folder(s) containing test cases for each language supported
   - Passing test case(s) per language denoted in naming scheme
+    - **FORMAT:** `LANGUAGE_(TYPE)_FILE.EXTENSION`
+    - **Example:** `markdown_good_5.md`
+    - **Note:** This allows the process to understand if linting of the file should pass or fail\
+    - **Note:** (good=Standard linting should be successful bad=standard linting should fail )
   - Failing test case(s) per language denoted in naming scheme
+    - **FORMAT:** `LANGUAGE_(TYPE)_FILE.EXTENSION`
+    - **Example:** `markdown_bad_5.md`
+    - **Note:** (good=Standard linting should be successful bad=standard linting should fail )
 - Script to run test cases and validate the sanity of **Super-Linter**

.automation/test/ansible/README.md

@@ -0,0 +1,13 @@
+# Ansible Test Cases
+This folder holds the test cases for **Ansible**.  
+
+## Additional Docs
+The folder **ghe-initialize** is pulled from the **GitHub-Demo-Stack** and is a valid **Ansible** role.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/coffeescript/README.md

@@ -0,0 +1,13 @@
+# Coffeescript Test Cases
+This folder holds the test cases for **Coffeescript**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/docker/README.md

@@ -0,0 +1,13 @@
+# Docker Test Cases
+This folder holds the test cases for **Docker**.  
+
+## Additional Docs
+Due to the nature of the naming of files, we have `2` subfolders in this directory.
+- `good` is for working, and correct **Dockerfile**(s)
+- `bad` is for invalid, and incorrect **Dockerfile**(s)
+
+## Good Test Cases
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/javascript/README.md

@@ -0,0 +1,13 @@
+# Javascript Test Cases
+This folder holds the test cases for **Javascript**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/json/README.md

@@ -0,0 +1,13 @@
+# Json Test Cases
+This folder holds the test cases for **Json**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/markdown/README.md

@@ -0,0 +1,13 @@
+# Markdown Test Cases
+This folder holds the test cases for **Markdown**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/perl/README.md

@@ -0,0 +1,13 @@
+# Perl Test Cases
+This folder holds the test cases for **Perl**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/python/README.md

@@ -0,0 +1,13 @@
+# Python Test Cases
+This folder holds the test cases for **Python**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/ruby/README.md

@@ -0,0 +1,13 @@
+# Ruby Test Cases
+This folder holds the test cases for **Ruby**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/shell/README.md

@@ -0,0 +1,13 @@
+# Bash Test Cases
+This folder holds the test cases for **Bash**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/xml/README.md

@@ -0,0 +1,13 @@
+# XML Test Cases
+This folder holds the test cases for **XML**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

.automation/test/yml/README.md

@@ -0,0 +1,13 @@
+# Yml Test Cases
+This folder holds the test cases for **Yml**.  
+
+## Additional Docs
+No Additional information is needed for this test case.
+
+## Good Test Cases
+The test cases denoted: `LANGUAGE_good_FILE.EXTENSION` are all valid, and should pass successfully when linted.
+- **Note:** They are linted utilizing the default linter rules.
+
+## Bad Test Cases
+The test cases denoted: `LANGUAGE_bad_FILE.EXTENSION` are **NOT** valid, and should trigger errors when linted.
+- **Note:** They are linted utilizing the default linter rules.

README.md

@@ -17,13 +17,11 @@ Developers on **GitHub** can call this Action to lint their code base with the f
 
 ## How to use
 To use this **GitHub** Action you will need to complete the following:
-- Copy **any** or **all** template rules files from `TEMPLATES/` into your repository in the location: `.github/linters/`
-  - If your repository does not have rules files, they will fall back to defaults in this repositories `TEMPLATE` folder
 - Add the **GitHub** Action: **Super-Linter** to your current **GitHub** Actions workflow
 - Enjoy your more *stable*, and *cleaner* code base
 
 ### Example connecting GitHub Action Workflow
-In your repository you should have a `workflows` folder with **GitHub** Action similar to below:
+In your repository you should have a `.github/workflows` folder with **GitHub** Action similar to below:
 
 - `.github/workflows/linter.yml`
 
@@ -124,6 +122,14 @@ The super-linter allows you to pass the following `ENV` variables to be able to
 - **VALIDATE_DOCKER**
   - Default: `true`
   - Flag to enable or disable the linting process of the language  
+- **VERBOSE_OUTPUT**
+  - Default: `false`
+  - Flag to enable additional information about the linter, versions, and additional output
+
+### Template rules files
+You can use the **GitHub** **Super-Linter** *with* or *without* your own personal rules sets. This allows for greater flexibility for each individual code base. The Template rules all try to follow the standards we believe should be enabled at the basic level.
+- Copy **any** or **all** template rules files from `TEMPLATES/` into your repository in the location: `.github/linters/` of your repository
+  - If your repository does not have rules files, they will fall back to defaults in this repositories `TEMPLATE` folder
 
 ## Docker Hub
 The **Docker** container that is built from this repository is located at `https://cloud.docker.com/u/admiralawkbar/repository/docker/admiralawkbar/super-linter`
@@ -131,6 +137,15 @@ The **Docker** container that is built from this repository is located at `https
 ## Running Super-Linter locally (troubleshooting/debugging/enhancements)
 If you find that you need to run super-linter locally, you can follow the documentation at [Running super-linter locally](https://github.com/github/super-linter/blob/master/.github/run-linter-locally.md)
 
+### CI/CT/CD
+The **Super-Linter** has *CI/CT/CD* configured utilizing **GitHub** Actions.
+- When a branch is created and code is pushed, a **GitHub** Action is triggered for building the new **Docker** container with the new codebase
+- The **Docker** container is then ran against the *test cases* to validate all code sanity
+  - `.automation/test` contains all test cases for each language that should be validated
+- These **GitHub** Actions utilize the Checks API and Protected Branches to help follow the SDLC
+- When the Pull Request is merged to master, the **Super-Linter** **Docker** container is then updated and deployed with the new codebase
+  - **Note:** The branches **Docker** container is also removed from **DockerHub** to cleanup after itself
+
 ## How to contribute
 If you would like to help contribute to this **GitHub** Action, please see [CONTRIBUTING](https://github.com/github/super-linter/blob/master/.github/CONTRIBUTING.md)