Merge pull request #146 from wayofdev/ci/e2e-testing

wayofdev · Jun 12, 2024 · 30f741d · 30f741d
2 parents e7ad086 + ded9951
commit 30f741d
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 48 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1,32 +1,61 @@
 # Contributing
 
-If you would like to contribute to this project, please open an issue or a pull request. We are always looking for ways to improve the project and would love to hear your ideas.
+Welcome to our project!
 
-The latest changes are always in master branch, so please make your Pull Request against that branch.
+We appreciate your interest in contributing. This guide will help you get started, ensuring an effective collaboration.
+
+<br>
+
+## 🗂 Table of Contents
+
+* [Introduction](#-introduction)
+* [Development Requirements](#-development-requirements)
+  * [Optional Tools](#-optional-tools)
+* [Using the Makefile](#-using-the-makefile)
+* [Workflow](#-workflow)
+* [Continuous Integration with GitHub Actions](#-continuous-integration-with-github-actions)
+* [Before You Contribute](#-before-you-contribute)
+* [Commit Message Guidelines](#-commit-message-guidelines)
+* [Coding Standards and Tools](#-coding-standards-and-tools)
+  * [Yaml Lint](#-yaml-lint)
+  * [Action Lint](#-action-lint)
+  * [Markdown Lint](#-markdown-lint)
+* [Tests](#-tests)
+* [Pre-commit Hooks](#-pre-commit-hooks)
+  * [Configured Hooks](#-configured-hooks)
+  * [Installing Pre-commit Hooks](#-installing-pre-commit-hooks)
+
+<br>
+
+## 👋 Introduction
+
+If you would like to contribute, please **open an issue** or a pull request. We are always looking for ways to improve the project and would love to hear your ideas.
+
+The latest changes are always in **`master`** branch, so please make your Pull Request against that branch.
 
 <br>
 
 ## 🚩 Development Requirements
 
 Before you begin, you will need to set up your local development environment. Here is what you'll need:
 
-- **Operating System**: macOS Monterey+, Linux, or Windows with WSL2.
-- **Docker**: Version 26.0.0 or newer. Installation guides:
-  - [How To Install and Use Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
-  - [How To Install Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)
-- **Homebrew** (macOS only): Install via [brew.sh](https://brew.sh/).
-- **mkcert** Install via [brew.sh/formula/mkcert](https://formulae.brew.sh/formula/mkcert#default) or follow their instructions [here](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#installation).
+* **Operating System**: macOS Monterey+, Linux, or Windows with WSL2.
+* **Docker**: Version 26.0.0 or newer. Installation guides:
+  * [How To Install and Use Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
+  * [How To Install Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)
+* **Homebrew** (macOS only): Install via [brew.sh](https://brew.sh/).
+* **mkcert** Install via [brew.sh/formula/mkcert](https://formulae.brew.sh/formula/mkcert#default) or follow their instructions [here](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#installation).
 
 ### → Optional Tools
 
-- [Pre-commit](https://pre-commit.com) — Automates the running of git pre-commit hooks.
-  - Installation: `brew install pre-commit` and `make hooks`
-- [Cz-git](https://cz-git.qbb.sh) — Commitizen adapter, that assists in formatting git commits.
-  - Installation: `brew install czg`
+* [Pre-commit](https://pre-commit.com) — Automates the running of git pre-commit hooks.
+  * Installation: `brew install pre-commit` and `make hooks`
+* [Cz-git](https://cz-git.qbb.sh) — Commitizen adapter, that assists in formatting git commits.
+  * Installation: `brew install czg`
 
 <br>
 
-## 🛠️ Makefile
+## 🔧 Using the Makefile
 
 This project uses a Makefile to streamline common development tasks. The Makefile includes utilities for managing Docker environments, running tests, and linting code.
 
@@ -38,14 +67,14 @@ make help
 
 ### → Key Commands
 
-- `make up`: Starts all services using Docker Compose.
-- `make up-router`: Starts only traefik router container.
-- `make up-dns`: Starts only dnsmasq container.
-- `make down`: Stops and removes all services.
-- `make stop`: Stops all services.
-- `make logs`: Displays logs for all services.
-- `make lint`: Executes all linting procedures for YAML, PHP, and Composer files.
-- `make commit`: Runs cz-git, a commitizen adapter for commit message formatting in a native environment.
+* `make up`: Starts all services using Docker Compose.
+* `make up-router`: Starts only traefik router container.
+* `make up-dns`: Starts only dnsmasq container.
+* `make down`: Stops and removes all services.
+* `make stop`: Stops all services.
+* `make logs`: Displays logs for all services.
+* `make lint`: Executes all linting procedures for YAML, PHP, and Composer files.
+* `make commit`: Runs cz-git, a commitizen adapter for commit message formatting in a native environment.
 
 Refer to the output of `make help` for a comprehensive list of available commands.
 
@@ -57,40 +86,41 @@ Refer to the output of `make help` for a comprehensive list of available command
 >
 > Please feature/fix/update... into individual PRs (not one changing everything)
 
-- **Fork the Repository**: Start by forking the repository to your GitHub account.
-- **Create a Branch**: In your fork, create a new branch for your work. Name it appropriately based on the feature, fix, or update you're working on.
-- **Make Your Changes**: Implement your changes
-- **Run Tests**: Ensure all tests pass and the code adheres to the coding standards.
-- **Update Documentation**: If you've made changes that affect the project's documentation, ensure it is updated.
-- **Run Linters**: Ensure your code passes all linting checks using `make lint`.
-- **Commit Your Changes**: Use the [Conventional Commits](#-commit-message-guidelines) standard for your commit messages. You can use `make commit` to assist in creating commit messages.
-- **Push Your Changes**: Push your branch to your fork on GitHub.
-- **Open a Pull Request**: Submit a pull request to the `master` branch of the original repository. Ensure your PR is focused, addressing a single feature, fix, or improvement.
+* **Fork the Repository**: Start by forking the repository to your GitHub account.
+* **Create a Branch**: In your fork, create a new branch for your work. Name it appropriately based on the feature, fix, or update you're working on.
+* **Make Your Changes**: Implement your changes
+* **Run Tests**: Ensure all tests pass and the code adheres to the coding standards.
+* **Update Documentation**: If you've made changes that affect the project's documentation, ensure it is updated.
+* **Run Linters**: Ensure your code passes all linting checks using `make lint`.
+* **Commit Your Changes**: Use the [Conventional Commits](#-commit-message-guidelines) standard for your commit messages. You can use `make commit` to assist in creating commit messages.
+* **Push Your Changes**: Push your branch to your fork on GitHub.
+* **Open a Pull Request**: Submit a pull request to the `master` branch of the original repository. Ensure your PR is focused, addressing a single feature, fix, or improvement.
 
 <br>
 
-## ⚡️ Continuous Integration with GitHub Actions
+## 🔨 Continuous Integration with GitHub Actions
 
 Our project employs [GitHub Actions](https://github.com/features/actions) for continuous integration, ensuring code quality and reliability. We encourage contributors to review our workflow configurations to understand the CI processes:
 
-| Workflow                                                      | Description                                        |
-|---------------------------------------------------------------|----------------------------------------------------|
-| [`apply-labels.yml`](workflows/apply-labels.yml)              | Auto labels PRs based on rules.                    |
-| [`auto-merge-release.yml`](workflows/auto-merge-release.yml)  | Automatically merges release PRs.                  |
-| [`coding-standards.yml`](workflows/coding-standards.yml)      | Checks `yaml`, `md` and commit coding standards.   |
-| [`create-release.yml`](workflows/create-release.yml)          | Creates a new release based on tags.               |
-| [`e2e-macos.yml`](workflows/e2e-macos.yml)                    | End-to-end tests on macOS. **Currently disabled**  |
-| [`e2e-ubuntu.yml`](workflows/e2e-ubuntu.yml)                  | End-to-end tests on Ubuntu. **Currently disabled** |
-| [`shellcheck.yml`](workflows/shellcheck.yml)                  | Lints shell scripts.                               |
+| Workflow                                                     | Description                                        |
+|--------------------------------------------------------------|----------------------------------------------------|
+| [`apply-labels.yml`](workflows/apply-labels.yml)             | Auto labels PRs based on rules.                    |
+| [`auto-merge-release.yml`](workflows/auto-merge-release.yml) | Automatically merges release PRs.                  |
+| [`coding-standards.yml`](workflows/coding-standards.yml)     | Checks `yaml`, `md` and commit coding standards.   |
+| [`create-release.yml`](workflows/create-release.yml)         | Creates a new release based on tags.               |
+| [`e2e-macos.yml`](workflows/e2e-macos.yml)                   | End-to-end tests on macOS. **Currently disabled**  |
+| [`e2e-ubuntu.yml`](workflows/e2e-ubuntu.yml)                 | End-to-end tests on Ubuntu. **Currently disabled** |
+| [`shellcheck.yml`](workflows/shellcheck.yml)                 | Lints shell scripts.                               |
+| [`sync-from-tpl.yml`](workflows/shellcheck.yml)              | Triggered only on down-stream templates.           |
 
 <br>
 
 ## 📝 Before You Contribute
 
-- **Tests**: Include tests that cover any new features or bug fixes, if applicable.
-- **Code Quality**: Utilize `make lint` for code style checks.
-- **Documentation**: Update relevant documentation to reflect your changes, ensuring other developers can understand and use your contributions effectively.
-- **Commits**: use Conventional Commits standard to create a commit
+* **Tests**: Include tests that cover any new features or bug fixes, if applicable.
+* **Code Quality**: Utilize `make lint` for code style checks.
+* **Documentation**: Update relevant documentation to reflect your changes, ensuring other developers can understand and use your contributions effectively.
+* **Commits**: use Conventional Commits standard to create a commit
 
 <br>
 
@@ -186,10 +216,12 @@ Pre-commit hooks are an optional but highly recommended way to automate the lint
 
 Our pre-commit configuration includes several hooks:
 
-- **Trailing Whitespace**: Removes unnecessary trailing spaces.
-- **End-of-File Fixer**: Ensures that files end with a newline.
-- **Check Added Large Files**: Prevents accidentally adding large files to the git repository, with a current limit set to 600 KB.
-- **Commitizen**: Ensures commit messages meet the conventional commit format. This hook is triggered at the commit message stage.
+* **Trailing Whitespace**: Removes unnecessary trailing spaces.
+* **End-of-File Fixer**: Ensures that files end with a newline.
+* **Check Added Large Files**: Prevents accidentally adding large files to the git repository, with a current limit set to 600 KB.
+* **Commitizen**: Ensures commit messages meet the conventional commit format. This hook is triggered at the commit message stage.
+
+* **Markdown Lint:** Enforces coding standards in Markdown files.
 
 ### → Installing Pre-commit Hooks
 

diff --git a/README.md b/README.md
@@ -31,6 +31,7 @@ It includes a set of docker-compose files and [Træfik](https://traefik.io/) con
 
 - [Key Features](#-key-features)
 - [Purpose](#-purpose)
+- [Benefits for Team](#-benefits-for-team)
 - [Requirements](#-requirements)
 - [Quick Start Guide (macOS)](#-quick-start-guide-macos)
 - [Quick Start Guide (Linux)](#-quick-start-guide-linux)