Update documentation (#4981)

* Update documentation

* Fix typos

* Update security policy

* Remove outdated instructions

* Fix list

* Add more info to config load step

* Don't test linter.yml

* Point to the cd workflow in README

* Move badge up

* Add info about Make help

---------

Co-authored-by: Zack Koppert <zkoppert@github.com>

.github/CONTRIBUTING.md

@@ -1,67 +1,28 @@
 # Contributing
 
 :wave: Hi there!
-We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
 
-## Submitting a pull request
-
-[Pull Requests][pulls] are used for adding new playbooks, roles, and documents to the repository, or editing the existing ones.
-
-**With write access**
-
-1. Clone the repository (only if you have write access)
-1. Create a new branch: `git checkout -b my-branch-name`
-1. Make your change
-1. Push and [submit a pull request][pr]
-1. Pat yourself on the back and wait for your pull request to be reviewed and merged.
-
-**Without write access**
-
-1. [Fork][fork] and clone the repository
-1. Create a new branch: `git checkout -b my-branch-name`
-1. Make your change
-1. Push to your fork and [submit a pull request][pr]
-1. Pat your self on the back and wait for your pull request to be reviewed and merged.
-
-Here are a few things you can do that will increase the likelihood of your pull request being accepted:
+We're thrilled that you'd like to contribute to this project.
+Your help is essential for keeping it great.
 
-- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
-- Write [good commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
-
-Draft pull requests are also welcome to get feedback early on, or if there is something blocking you.
-
-- Create a branch with a name that identifies the user and nature of the changes (similar to `user/branch-purpose`)
-- Open a pull request
-
-### CI/CT/CD
-
-The **Super-Linter** has _CI/CT/CD_ configured utilizing **GitHub** Actions.
+## Submitting a pull request
 
-- 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 main, the **Super-Linter** **Docker** container is then updated and deployed with the new codebase
-  - **Note:** The branch's **Docker** container is also removed from **DockerHub** to cleanup after itself
+We use [pull requests](https://github.com/super-linter/super-linter/pulls) to
+contribute new features, fixes, or documentation.
 
-## Releasing
+Here are a few things you can do that will increase the likelihood of your pull
+request being accepted:
 
-If you are the current maintainer of this action you can create releases from the `Release` page  of the repository.
+- Keep your change as focused as possible. If there are multiple changes you
+  would like to make that are not dependent upon each other, submit them as
+  separate pull requests.
+- Write [descriptive commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
-- It will notify the issue it has seen the information and starts the Actions job
-- It will create a branch and update the `actions.yml` with the new version supplied to the issue
-- It will then create a PR with the updated code
-- It will then create the build the artifacts needed
-- it will then publish the release and merge the PR
-- A GitHub Action will Publish the Docker image to GitHub Package Registry once a Release is created
-- A GitHub Action will Publish the Docker image to Docker Hub once a Release is created
+Draft pull requests are also welcome to get feedback early on, or if there is
+something blocking you.
 
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
 - [Using Pull Requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
 - [GitHub Help](https://docs.github.com/en)
-
-[pulls]: https://github.com/super-linter/super-linter/pulls
-[pr]: https://github.com/super-linter/super-linter/compare
-[fork]: https://github.com/super-linter/super-linter/fork

SECURITY.md

@@ -1,5 +1,17 @@
-# Security Policy
+# Reporting Security Issues
 
-If you discover a security issue in this repository, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
+The super-linter team and community take security bugs seriously. We appreciate
+your efforts to responsibly disclose your findings, and will make every effort
+to acknowledge your contributions.
 
-Thanks for helping make GitHub Actions safe for everyone.
+To report a security issue, please use the GitHub Security Advisory
+["Report a Vulnerability"](https://github.com/super-linter/super-linter/security/advisories/new)
+feature.
+
+The super-linter team will send a response indicating the next steps in handling
+your report. After the initial reply to your report, the security team will keep
+you informed of the progress towards a fix and full announcement, and may ask
+for additional information or guidance.
+
+Report security bugs in third-party software to the person or team maintaining
+the third-party software.

docs/run-linter-locally.md

@@ -1,128 +1,84 @@
-# Run Super-Linter locally to test your branch of code
+# Run super-linter outside GitHub Actions
 
-If you want to test locally against the **Super-Linter** to test your branch of
-code or to reproduce an issue, do the following:
+If you want to run super-linter outside GitHub Actions, you need a container
+runtime engine to run the super-linter container image.
 
-- Clone your testing source code to your local environment
-- Install Docker to your local environment
-- Pull the container
-- Run the container locally
+## Run super-linter Locally
 
-If you're contributing to Super-Linter, you also need to do following:
-
-- Run the test suite locally
-
-## Install Docker to your local machine
-
-You can follow the link below on how to install and configure **Docker** on your local machine
-
-- [Docker Install Documentation](https://docs.docker.com/install/)
-
-## Download the latest Super-Linter Docker container
-
-- Pull the latest **Docker** container image from the registry
-  - `docker pull ghcr.io/super-linter/super-linter:latest`
-    Once the container has been downloaded to your local environment, you can then begin the process, or running the container against your codebase.
-
-## Run the container Locally
-
-You can run the container locally with the following flags to run your code:
+You can run the container locally with the following configuration options to run your code:
 
 ```bash
 docker run \
   -e ACTIONS_RUNNER_DEBUG=true \
   -e RUN_LOCAL=true \
   -v /path/to/local/codebase:/tmp/lint \
+  --rm \
   ghcr.io/super-linter/super-linter:latest
 ```
 
 This example uses the `latest` container image version. If you're trying to reproduce
-an issue, **refer to a specific version instead**.
+an issue, or running super-linter as part of your CI pipeline, we recommend that
+you **refer to a specific version instead**.
 
 Notes:
 
 - To run against a single file you can use: `docker run -e RUN_LOCAL=true -e USE_FIND_ALGORITHM=true -v /path/to/local/codebase/file:/tmp/lint/file ghcr.io/super-linter/super-linter`
-- You need to pass the `RUN_LOCAL` flag to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to `/tmp/lint`.
+- You need to pass the `RUN_LOCAL` option to bypass some of the GitHub Actions checks, as well as the mapping of your local codebase to `/tmp/lint`.
 - If you want to override the `/tmp/lint` folder, you can set the `DEFAULT_WORKSPACE` environment variable to point to the folder you'd prefer to scan.
-- The flag:`RUN_LOCAL` will set: `VALIDATE_ALL_CODEBASE` to true. This means it will scan **all** the files in the directory you have mapped. If you want to only validate a subset of your codebase, map a folder with only the files you wish to have linted.
-- Add the `--rm` docker flag to automatically removes the container after execution.
-- You can add as many flags as needed. Flags are documented in the [README](../README.md#Environment-variables).
+- You can add as many configuration options as needed. Configuration options are documented in the [README](../README.md#configure-super-linter).
 
-## Sharing Environment variables between Local and CI
+### Azure
 
-If you run both locally and on CI it's very helpful to only have to define your env variables once.
-This is one setup using Github's [STRTA](https://github.com/github/scripts-to-rule-them-all) style to do so.
+Check out this [article](https://blog.tyang.org/2020/06/27/use-github-super-linter-in-azure-pipelines/)
 
-### .github/super-linter.env
+### GitLab
 
-This is the shared location for the super-linter variables. Example:
+Check out this [snippet](https://gitlab.com/snippets/1988376) and this Guided Exploration: [GitLab CI CD Extension for Super-Linter](https://gitlab.com/guided-explorations/ci-cd-plugin-extensions/ci-cd-plugin-extension-github-action-super-linter)
 
-```bash
-VALIDATE_ALL_CODEBASE=true
-VALIDATE_DOCKERFILE_HADOLINT=false
-VALIDATE_EDITORCONFIG=false
-VALIDATE_GITLEAKS=false
-```
+### Run on Codespaces and Visual Studio Code
 
-### scripts/lint
+This repository provides a DevContainer for [remote development](https://code.visualstudio.com/docs/remote/containers).
 
-This always runs the local docker based linting.
+## Share Environment variables between environments
 
-```bash
-docker run --rm \
-    -e RUN_LOCAL=true \
-    --env-file ".github/super-linter.env" \
-    -v "$PWD":/tmp/lint ghcr.io/super-linter/super-linter:latest
-```
+To avoid duplication if you run super-linter both locally and in other
+environements, such as CI, you can define configuration options once, and load
+them accordingly:
 
-### scripts/test
+1. Create a configuration file for super-linter `super-linter.env`. For example:
 
-This runs the local lint when not on CI.
+    ```bash
+    VALIDATE_ALL_CODEBASE=true
+    ```
 
-```bash
-if [ "$(whoami)" == "runner" ]; then
-  echo "We are on GitHub, so don't run lint manually"
-else
-  echo "Running locally because we don't think we are on GitHub"
-  lint_ci
-fi
-```
-
-### .github/workflows/ci.yml
+1. Load the super-linter configuration file when running outside GitHub Actions:
 
-This loads the environment variables before running the GitHub Actions job.
+    ```bash
+    docker run --rm \
+        -e RUN_LOCAL=true \
+        --env-file ".github/super-linter.env" \
+        -v "$(pwd)":/tmp/lint \
+        ghcr.io/super-linter/super-linter:latest
+    ```
 
-```yaml
-name: CI
+1. Load the super-linter configuration file when running in GitHub Actions by
+  adding the following step to the GitHub Actions workflow that runs
+  super-linter, after checking out your repository and before running
+  super-linter:
 
-on:
-  pull_request:
-
-jobs:
-  lint:
-    # Run GH Super-Linter against code base
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: cat .github/super-linter.env >> "$GITHUB_ENV"
-      - name: Lint Code Base
-        uses: super-linter/super-linter@v5
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: main
-```
+    ```yaml
+    - name: Load super-linter configuration
+      run: cat .github/super-linter.env >> "$GITHUB_ENV"
+    ```
 
 ## Build the container image and run the test suite locally
 
-You can run the test suite locally with the following command:
+You can run the build and test process locally with the following command:
 
 ```shell
 make
 ```
 
-The test suite will build the container image and run the test suite against a
-a container that is an instance of that container image.
-
 ### Run the test suite against an arbitrary super-linter container image
 
 You can run the test suite against an arbitrary super-linter container image.
@@ -142,15 +98,10 @@ Initialize the `BUILD_DATE`, `BUILD_REVISION`, and `BUILD_VERSION` variables
 with the values for that specific container image version. You can get these
 values from the build log for that version.
 
-## Troubleshooting
+### Get the list of available build targets
 
-### Run container and gain access to the command-line
+To get the list of the available `Make` targets, run the following command:
 
-If you need to run the container locally and gain access to its command-line, you can run the following command:
-
-- `docker run -it --entrypoint /bin/bash ghcr.io/super-linter/super-linter`
-- This will drop you in the command-line of the docker container for any testing or troubleshooting that may be needed.
-
-### Found issues
-
-If you find a _bug_ or _issue_, please open a **GitHub** issue at: [super-linter/super-linter/issues](https://github.com/super-linter/super-linter/issues)
+```shell
+make help
+```