Merge pull request #409 from wayofdev/docs/updates

Author: lotyp

.github/CONTRIBUTING.md

@@ -0,0 +1 @@
+To be added...

.github/assets/deployments.png

@@ -11,7 +11,7 @@
 
 "type: documentation":
   - changed-files:
-      - any-glob-to-any-file: ['assets/**/*', '.github/*', './*.md']
+      - any-glob-to-any-file: ['.github/*', './*.md']
 
 "type: maintenance":
   - changed-files:

.github/labeler.yml

@@ -282,7 +282,7 @@ lint-deptrac-ci: ## Runs deptrac – static analysis tool with github output (CI
 .PHONY: lint-deptrac-ci
 
 lint-deptrac-gv: ## Runs deptrac – static analysis tool and generates graphviz image
-	$(APP_RUNNER) .phive/deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache --formatter graphviz-image --output ../assets/deptrac.svg
+	$(APP_RUNNER) .phive/deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache --formatter graphviz-image --output ../.github/assets/deptrac.svg
 .PHONY: lint-deptrac-gv
 
 lint-composer: ## Normalize composer.json and composer.lock files

Makefile

@@ -54,31 +54,67 @@ This repository provides a modified file structure for Laravel that follows DDD
 
 This starter template includes several added, changed, and removed features:
 
+### → Framework Modifications
+
 * **Added:**
   * Strict types declaration in all PHP files
+  * Application dockerization using docker-compose and Makefile — use `make help` to view available commands
+  * [spatie/laravel-route-attributes](https://github.com/spatie/laravel-route-attributes) package for route definition using PHP8 style attributes
+
+* **Changed:**
+  * Marked default Laravel classes as `final`
+  * Modified file structure to meet DDD principles (as close as possible)
+  * Changed config folder files to use default PHP multi-line comment style
+
+* **Removed:**
+  * Dependencies like Laravel Sanctum, Laravel Pint, and Laravel Sail
+  * Broadcasting service provider and its routes. It can be added back if required for the project
+  * Console routes in favor of Command classes
+  * Sanctum migration files
+
+### → Development Tools
+
+* **Added:**
   * Style checker package for custom rule-sets to php-cs-fixer — [wayofdev/php-cs-fixer-config](https://github.com/wayofdev/php-cs-fixer-config)
+  * [Phive](https://github.com/phar-io/phive) support for managing PHP tools
+    * [ergebnis/composer-normalize](https://github.com/ergebnis/composer-normalize) composer plugin for normalizing composer.json file
+    * [maglnet/ComposerRequireChecker](https://github.com/maglnet/ComposerRequireChecker) to check whether a specific composer package uses imported symbols that aren't part of its direct composer dependencies
+  * Application dockerization using docker-compose and Makefile — use `make help` to view available commands
+    * [docker-php-dev](https://github.com/wayofdev/docker-php-dev) as PHP development environment with XDebug support out of the box
+
+### → Testing
+
+* **Added:**
+  * Configured [PHPUnit](https://phpunit.de/index.html) for unit testing.
+  * Integrated [Pest PHP](https://pestphp.com) for elegant console support and architecture testing.
+  * [Infection](https://github.com/infection/infection) for mutation testing to ensure quality.
+  * Mutation test reports are uploaded [Stryker Mutator Dashboard](https://dashboard.stryker-mutator.io).
+
+### → Static Analysis
+
+* **Added:**
   * Static analysis tool — [PHPStan](https://phpstan.org) and it's extensions:
     * [phpstan/extension-installer](https://github.com/phpstan/extension-installer) — automatic installation of PHPStan extensions
     * [phpstan/phpstan-deprecation-rules](https://github.com/phpstan/phpstan-deprecation-rules) — rules for detecting usage of deprecated classes, methods, properties, constants and traits.
-    * [nunomaduro/larastan](https://github.com/nunomaduro/larastan) — PHPStan integration with Laravel
-  * [Pest](https://pestphp.com) testing framework
-  * Github action workflows for:
+    * [larastan/larastan](https://github.com/larastan/larastan) for Laravel-specific static analysis.
+  * [Psalm](https://github.com/vimeo/psalm) static analysis tool and it's extensions:
+    * [psalm/plugin-laravel](https://github.com/psalm/psalm-plugin-laravel) — Psalm plugin for Laravel
+    * [psalm/plugin-phpunit](https://github.com/psalm/psalm-plugin-phpunit) — Psalm plugin for PHPUnit
+  * [PHP Rector](https://github.com/rectorphp/rector) for automated code upgrades and refactoring, maintaining modern code standards.
+
+### → Continuous Integration
+
+* **Added:**
+  * GitHub action workflows for:
     * Continuous integration which includes coding standards checks, unit testing and static analysis
     * Automatic pull-request labeling
-    * [Deployer](https://deployer.org) for automatic deployments to staging and production servers with support of [Github Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
-  * [ergebnis/composer-normalize](https://github.com/ergebnis/composer-normalize) composer plugin for normalizing composer.json file
-  * [roave/securityadvisories](https://github.com/Roave/SecurityAdvisories) package to ensure that application doesn't have installed dependencies with known security vulnerabilities.
-  * Application dockerization using docker-compose and Makefile — use `make help` to view available commands
   * Git pre-commit hooks using [pre-commit](https://pre-commit.com) package
-* **Changed:**
-  * Marked default Laravel classes as `final`
-  * Modified file structure to meet DDD principles
-  * Changed config folder files to use default PHP multi-line comment style
-* **Removed:**
-  * Dependencies like Laravel Sanctum, Laravel Pint, and Laravel Sail.
-  * Broadcasting service provider and it's routes. It can be added back, if it will be required for project
-  * Console routes in favor of Command classes.
-  * Sanctum migration files
+
+### → Deployments
+
+* **Added:**
+  * [Deployer](https://deployer.org) for automatic deployments to staging and production servers with support of [GitHub Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
+  * For more information see [Deployments](#-deployment-to-staging-and-production) section
 
 <br>
 
@@ -89,14 +125,14 @@ To use this repository, you need to meet the following requirements:
 * **macOS** Monterey+ or **Linux**
 * Docker 20.10 or newer
   * [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)
-* Installed **dnsmasq** service, running in the system. You can use [ansible-role-dnsmasq](https://github.com/wayofdev/ansible-role-dnsmasq) to install and configure this service.
 * **Cloned, configured and running** [docker-shared-services](https://github.com/wayofdev/docker-shared-services) to support system-wide DNS, routing, and TLS support via Traefik.
 
 <br>
 
 ## 💿 Installation
 
-> Warning: You should configure, set up, and run the [docker-shared-services](https://github.com/wayofdev/docker-shared-services) repository to ensure system-wide TLS and DNS support.
+> [!Note]
+> You should configure, set up, and run the [docker-shared-services](https://github.com/wayofdev/docker-shared-services) repository to ensure system-wide TLS and DNS support.
 
 1. **Clone** repository:
 
@@ -144,9 +180,35 @@ To use this repository, you need to meet the following requirements:
 
 <br>
 
-## 🤝 License
+## 🤖 Deployment to Staging and Production
+
+This repository utilizes GitHub Actions for continuous deployment to both staging and production servers. Below is a description.
+
+### → Deployment Flow
+
+#### Deployment to Staging
+
+1. **Push to `develop` branch**: Initiates the deployment process to the staging server. Merge PR against `develop` branch, to trigger `deploy-staging.yml`
+2. **GitHub Actions**: Executes the `deploy-staging.yml` workflow.
+3. **Staging Server**: Receives deployment instructions and acknowledges the deployment.
 
-[![Licence](https://img.shields.io/github/license/wayofdev/laravel-starter-tpl?style=for-the-badge&color=blue)](./LICENSE)
+#### Deployment to Production
+
+1. **Merge of `develop` branch into `master`**: Triggers the deployment process to the production server on push event.
+2. **GitHub Actions**: Runs the `create-release.yml` workflow.
+3. **Release Event**: `deploy-release.yml` waits for the event `release: released`.
+4. **GitHub Actions**: Initiates the `deploy-release.yml` workflow.
+5. **Production Server**: Receives deployment instructions and acknowledges the deployment.
+
+#### Conditional Deployment Status
+
+* **Deployment Successful**: Both staging and production servers send a success message back to GitHub Actions. Additionally, a success message is sent to the Slack server.
+
+* **Deployment Failed**: If an error occurs, a failure message is sent back to GitHub Actions. Additionally, a failure message is sent to the Slack server.
+
+#### Diagram
+
+![deployments](.github/assets/deployments.png)
 
 <br>
 
@@ -155,24 +217,49 @@ To use this repository, you need to meet the following requirements:
 Useful resources about Laravel and DDD approach:
 
 * [Laravel Beyond CRUD](https://spatie.be/products/laravel-beyond-crud)
-* [Laravel Skeleton](https://romanzipp.github.io/Laravel-Skeleton/) by [romanzipp](https://github.com/romanzipp)
 
 <br>
 
-## 🙆🏼‍♂️ Author Information
+## 🔒 Security Policy
 
-This repository was created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev).
+This project has a [security policy](.github/SECURITY.md).
 
 <br>
 
 ## 🙌 Want to Contribute?
 
-Thank you for considering contributing to the wayofdev community!
-We are open to all kinds of contributions. If you want to:
+Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to:
 
-* 🤔 Suggest a feature
-* 🐛 Report an issue
-* 📖 Improve documentation
+* 🤔 [Suggest a feature](https://github.com/wayofdev/laravel-starter-tpl/issues/new?assignees=&labels=type%3A+enhancement&projects=&template=2-feature-request.yml&title=%5BFeature%5D%3A+)
+* 🐛 [Report an issue](https://github.com/wayofdev/laravel-starter-tpl/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=1-bug-report.yml&title=%5BBug%5D%3A+)
+* 📖 [Improve documentation](https://github.com/wayofdev/laravel-starter-tpl/issues/new?assignees=&labels=type%3A+documentation%2Ctype%3A+maintenance&projects=&template=4-docs-bug-report.yml&title=%5BDocs%5D%3A+)
 * 👨‍💻 Contribute to the code
 
+You are more than welcome. Before contributing, kindly check our [contribution guidelines](.github/CONTRIBUTING.md).
+
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org)
+
+<br>
+
+## 🫡 Contributors
+
+<p align="left">
+<a href="https://github.com/wayofdev/laravel-starter-tpl/graphs/contributors">
+<img align="left" src="https://img.shields.io/github/contributors-anon/wayofdev/laravel-starter-tpl?style=for-the-badge" alt="Contributors Badge"/>
+</a>
+<br>
+<br>
+</p>
+
+## 🌐 Social Links
+
+* **Twitter:** Follow our organization [@wayofdev](https://twitter.com/intent/follow?screen_name=wayofdev) and the author [@wlotyp](https://twitter.com/intent/follow?screen_name=wlotyp).
+* **Discord:** Join our community on [Discord](https://discord.gg/CE3TcCC5vr).
+
+<br>
+
+## ⚖️ License
+
+[![Licence](https://img.shields.io/github/license/wayofdev/laravel-starter-tpl?style=for-the-badge&color=blue)](./LICENSE.md)
+
 <br>

README.md

@@ -127,7 +127,7 @@
         "cs:fix": "php-cs-fixer fix -v",
         "deptrac": "deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache",
         "deptrac:ci": "deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache --formatter github-actions",
-        "deptrac:gv": "deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache --formatter graphviz-image --output ../assets/deptrac.svg",
+        "deptrac:gv": "deptrac analyse --config-file=deptrac.yaml -v --cache-file=.build/.deptrac.cache --formatter graphviz-image --output ../.github/assets/deptrac.svg",
         "infect": [
             "Composer\\Config::disableProcessTimeout",
             "@putenv XDEBUG_MODE=coverage",