Contributing
We appreciate your interest in contributing. This guide will help you get started, ensuring an effective collaboration.
👋 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.
🚩 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:
→ Optional Tools
Homebrew (macOS only)
Install via brew.sh.
Pre-commit — Automates the running of git pre-commit hooks.
Installation:
brew install pre-commitandmake hooks
Cz-git — Commitizen adapter, that assists in formatting git commits.
Installation:
brew install czg
🚀 Quick Project Setup
We use a dockerized environment. Follow these steps to start working with the project:
Clone this repository:
Create
.envfile:Install phive and composer dependencies:
🔧 Using the Makefile
This project uses a Makefile to streamline common development tasks. The Makefile includes utilities for managing Docker environments, installing project dependencies, running tests, and linting code.
→ Key Commands
make env: Creates a.envfile from the.env.exampletemplate.make install: Installs project composer dependenciesmake update: Updates project composer dependenciesmake up: Starts all services using Docker Compose.make down: Stops and removes all services.make logs: Displays logs for all services.make ssh: Logs into the running application container for command line operations.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.
For a full list of commands, run make help.
💻 Workflow
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 by running
make test.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 standard for your commit messages. You can use
make committo 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
masterbranch of the original repository. Ensure your PR is focused, addressing a single feature, fix, or improvement.
🐳 Docker Support
This package leverages Docker to provide a consistent and isolated development environment. The included Makefile utilizes docker-compose.yaml along with the wayofdev/docker-php-dev PHP image to streamline setup and usage. This setup facilitates easy configuration of tools like XDebug for debugging and profiling, enhancing the development experience.
To run docker container:
Other commands:
By default, phpunit and phpstan commands will be ran against docker environment.
🔨 Continuous Integration with GitHub Actions
Our project employs GitHub Actions for continuous integration, ensuring code quality and reliability. We encourage contributors to review our workflow configurations to understand the CI processes:
apply-labels.yml
Auto labels PRs based on rules.
coding-standards.yml
Checks yaml, md, composer, php and commit coding standards.
create-release.yml
Creates a release on GitHub.
dependency-analysis.yml
Checks for dependency issues.
refactoring.yml
Runs rector/rector code check.
security-analysis.yml
Checks for security issues.
shellcheck.yml
Checks shell scripts.
static-analysis.yml
Runs psalm and phpstan tools.
testing.yml
Runs coverage, mutation and functional tests against SQLite
testing-mysql.yml
Runs functional tests against MySQL
testing-pgsql.yml
Runs functional tests against PostgreSQL
testing-sqlserver.yml
Runs functional tests against SQLServer (MSSQL)
📝 Before You Contribute
Tests: Include tests that cover any new features or bug fixes.
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
📩 Commit Message Guidelines
We follow the Conventional Commits standard. Please structure your commit messages as follows, using the appropriate prefix:
Examples:
Allowed Prefixes:
feat:
Introduces a new feature
fix:
Fixes a bug
perf:
Improves performance
docs:
Documentation only changes
style:
Code style changes (formatting, missing semi-colons, etc.)
deps:
Updates dependencies
refactor:
Code changes that neither fixes a bug nor adds a feature
ci:
Changes to our CI configuration files and scripts
test:
Adding missing tests or correcting existing tests
revert:
Reverts a previous commit
build:
Changes that affect the build system or external dependencies
chore:
Other changes that don't modify src or test files
security:
A code change that fixes a security issue
📦 PHAR Dependencies
We use Phive to manage PHAR dependencies. You can install all dependencies using the make phive command, which will be executed through the Docker environment.
🔍 Coding Standards
We enforce coding standards to maintain high code quality and readability. Here's a list of tools we use:
→ Composer Normalization
We use ergebnis/composer-normalize to normalize composer.json.
Use:
→ Yaml Lint
We use yamllint to enforce coding standards in YAML files.
To lint yaml files run:
by default, cytopia/yamllint Docker image will be used to run linter.
→ Action Lint
We use actionlint to enforce coding standards in GitHub Actions workflows.
To lint GitHub Actions run:
by default, rhysd/actionlint Docker image will be used to run linter.
→ Markdown Lint
We use markdownlint-cli2 to enforce coding standards in Markdown files.
To lint markdown files run:
→ PHP CS Fixer
We use friendsofphp/php-cs-fixer together with wayofdev/php-cs-fixer-config to enforce coding standards in PHP files.
Run
to automatically fix coding standard violations.
→ Rector
We use rector/rector to refactor and modernize PHP code.
Run
to perform code refactoring.
🔬 Dependency Analysis
We use maglnet/composer-require-checker to prevent the use of unknown symbols in production code.
Run
to run a dependency analysis.
🔒 Security Audits
We use Composer's built-in audit feature to check for known vulnerabilities in dependencies.
Run
🦠 Mutation Tests
We use infection/infection together with roave/infection-static-analysis-plugin to ensure a minimum quality of the tests. Roave plugin is used to publish mutation score results to the Stryker Dashboard.
Xdebug support is enabled by default when running commands through the Makefile:
to run mutation tests.
🔍 Static Code Analysis
We use both phpstan/phpstan and vimeo/psalm to statically analyze the code.
Run
to run a static code analysis.
We also use the baseline features of phpstan/phpstan and vimeo/psalm to ignore existing issues.
Run
to regenerate the baselines in:
../phpstan-baseline.neon.../psalm-baseline.xml.
Ideally, the baseline files should stay empty or shrink over time.
🧪 Unit and Functional Tests
We use phpunit/phpunit and pestphp/pest to drive the development.
Run to run all the tests:
📦 Pre-commit Hooks
Pre-commit hooks are an optional but highly recommended way to automate the linting and quality checks before committing changes to the repository. This project provides a predefined configuration that helps in maintaining code quality and consistency.
→ Configured Hooks
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.
PHP-CS-Fixer: Enforces coding standards in PHP files.
Markdown Lint: Enforces coding standards in Markdown files.
→ Installing Pre-commit Hooks
To utilize these hooks, you first need to install them using the command provided by the Makefile:
Last updated