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:

→ Optional Tools

  • Homebrew (macOS only)

  • Pre-commit — Automates the running of git pre-commit hooks.

    • Installation: brew install pre-commit and make 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:

  1. Clone this repository:

    git clone [email protected]:cycle/active-record.git \
 && cd ./active-record

  2. Create .env file:

    make env

  3. Install phive and composer dependencies:

    make phive
make install

🔧 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.

make help
visual view of make help command

→ Key Commands

  • make env: Creates a .env file from the .env.example template.

  • make install: Installs project composer dependencies

  • make update: Updates project composer dependencies

  • make 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 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.

🐳 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:

make up

Other commands:

# Login inside container
$ make ssh

# Turn off containers
$ make down

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:

Workflow
Description

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.

  • Code Quality: Utilize make lint for code style checks and make lint-stan lint-psalm for static analysis with PHPStan and Psalm.

  • 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:

git commit -am 'feat: some feature was introduced'
git commit -am 'fix: something has been fixed'

Allowed Prefixes:

Prefix
Purpose

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.

make phive

🔍 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:

make lint-composer

→ Yaml Lint

We use yamllint to enforce coding standards in YAML files.

To lint yaml files run:

make lint-yaml

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:

make lint-actions

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:

make lint-md-dry
make lint-md

→ PHP CS Fixer

We use friendsofphp/php-cs-fixer together with wayofdev/php-cs-fixer-config to enforce coding standards in PHP files.

Run

make lint-php

to automatically fix coding standard violations.

→ Rector

We use rector/rector to refactor and modernize PHP code.

Run

make refactor

to perform code refactoring.

🔬 Dependency Analysis

We use maglnet/composer-require-checker to prevent the use of unknown symbols in production code.

Run

make lint-deps

to run a dependency analysis.

🔒 Security Audits

We use Composer's built-in audit feature to check for known vulnerabilities in dependencies.

Run

make lint-audit

🦠 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:

make infect

to run mutation tests.

🔍 Static Code Analysis

We use both phpstan/phpstan and vimeo/psalm to statically analyze the code.

Run

make lint-stan
make lint-psalm

to run a static code analysis.

We also use the baseline features of phpstan/phpstan and vimeo/psalm to ignore existing issues.

Run

make lint-stan-baseline
make lint-psalm-baseline

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:

# To run both, arch (pest) and unit (phpunit) tests
make test

# To run only arch (pest) tests
make test-arch

# To run only unit (phpunit) tests
make test-unit

📦 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:

make hooks
PreviousInstallationNextDefining Entities

Last updated