Contributing

This page explains how to contribute code to the ai-commit project: development environment setup, enforced coding standards, the test suite, the pull request process, the release workflow, and how CHANGELOG.md is maintained. For detailed information on the architecture you'll be working in, see the Architecture Deep Dive. For information on the test suite structure and helpers specifically, see Testing Framework.

---

Prerequisites

Requirement	Minimum version
PHP	8.2
Composer	2.x
Git	any recent version
Extensions	ext-curl, ext-mbstring

The project also relies on several Node.js-based linters for markdown and YAML (used in CI). They are optional for PHP-only changes.

---

Development Environment Setup

Clone the repository and install all dependencies, including dev and vendor-bin tools:

The post-install-cmd script in composer.json186-190 installs git hooks and updates all vendor-bin tool directories automatically.

vendor-bin Tools

The project uses bamarni/composer-bin-plugin to isolate dev tools in subdirectories under vendor-bin/. Tools managed this way include PHPStan extensions, Rector, PHP-CS-Fixer config, and monorepo-builder. Running composer install triggers the @composer-bin-all-update script to populate them.

Git Hooks (brainmaestro/composer-git-hooks)

Git hooks are defined in composer.json176-183 under the extra.hooks key:

Hook	Action
pre-commit	Runs composer checks
post-merge	Runs composer checks

The checks script is a sequenced suite of all quality gates (see below). Hooks are installed via cghooks add and can be refreshed with composer cghooks-install.

Sources: composer.json176-190

---

Composer Script Reference

The scripts section of composer.json185-438 defines the full development workflow. Key scripts are:

Script	Purpose
composer checks	Full sequential check suite (normalize, lint, style, static analysis, tests, rector)
composer pest	Run Pest test suite with coverage, enforcing 80% minimum
composer phpstan	Run PHPStan static analysis
composer style-lint	Dry-run PHP-CS-Fixer
composer style-fix	Apply PHP-CS-Fixer fixes
composer rector-dry-run	Run Rector in dry-run mode
composer rector	Apply Rector transformations
composer release	Trigger monorepo-builder release
composer release-patch	Release a patch version
composer release-minor	Release a minor version
composer release-major	Release a major version

The full checks sequence composer.json222-241:

env-put-xdebug-off →
composer-normalize → composer-validate →
md-lint → readme-lint → yaml-lint →
composer-validate-prefer-lowest →
phpmnd → style-lint →
sk-check-conflicts → sk-check-commented-code → sk-finalize-classes-dry-run →
composer-dependency-analyser → sk-spot-lazy-traits →
env-put-xdebug-on → pest →
env-put-xdebug-off → rector-dry-run → phpstan

Sources: composer.json222-241

---

Coding Standards

PHP-CS-Fixer

Style enforcement uses friendsofphp/php-cs-fixer configured at .php-cs-fixer.php (via the ergebnis/php-cs-fixer-config ruleset). Run:

• Check: composer style-lint
• Fix: composer style-fix

In CI, a dedicated workflow auto-commits style fixes. See CI/CD Workflows.

PHPStan

Static analysis runs at maximum level with several extensions and plugins:

• larastan/larastan for Laravel-aware analysis
• phpstan/phpstan-strict-rules, phpstan/phpstan-deprecation-rules
• spaze/phpstan-disallowed-calls for banned call detection
• tomasvotruba/type-coverage enforcing 100% type coverage
• tomasvotruba/cognitive-complexity enforcing cognitive complexity limits

Configuration lives in phpstan.neon. Run with:

To update the baseline:

Sources: composer.json96-123 .github/workflows/phpstan.yml1-41

Rector

Rector is configured in rector.php to apply dead code removal, code quality upgrades, PHP 8.2 upgrades, and Laravel-specific transformations. It runs in dry-run mode during CI and in the checks suite. Apply locally:

Key configured rules include StaticClosureRector, SortAssociativeArrayByKeyRector, JsonThrowOnErrorRector, and the full LaravelSetList and PHPUnitSetList sets. See Code Quality Tools for full detail.

Sources: rector.php71-297

Conventional Commits

All commit messages must follow the Conventional Commits format. The CHANGELOG.md is generated automatically from commit messages using git-chglog. Valid types are defined in .chglog/config.yml13-21:

Type	Changelog section
feat	✨ Features
fix	🐞 Bug Fixes
docs	📖 Documents
refactor	💅 Code Refactorings
perf	🏎 Performance Improvements
test	✅ Tests
build	📦 Builds
ci	🤖 Continuous Integrations
revert	⏪️ Reverts
style	🎨 Styles

chore commits are excluded from the changelog by the filter in .chglog/config.yml13-21

Sources: .chglog/config.yml1-76 .chglog/CHANGELOG.tpl.md1-63

---

Running Tests

The test suite uses Pest with the Laravel plugin. See Testing Framework for suite structure, HTTP fakes, and fixture helpers.

Coverage is collected via Xdebug (enabled by the env-put-xdebug-on script before test runs). The output is written to .build/phpunit/clover.xml and uploaded to Codecov in CI.

Sources: composer.json320-333 .github/workflows/tests.yml1-54

---

CI/CD Workflows

Diagram: GitHub Actions CI Pipeline

Workflow	File	Trigger	What it enforces
tests	.github/workflows/tests.yml	push, PR	Tests pass on PHP 8.2 & 8.4, Ubuntu & Windows
phpstan	.github/workflows/phpstan.yml	push (PHP files, neon, xml)	Static analysis clean
rector	.github/workflows/rector.yml	push (PHP files, yml, xml)	No unapplied Rector rules
secrets check	.github/workflows/secret-check.yml	push, PR	No verified/unknown secrets

Sources: .github/workflows/tests.yml1-54 .github/workflows/phpstan.yml1-41 .github/workflows/rector.yml1-40 .github/workflows/secret-check.yml1-25

---

Pull Request Workflow

Diagram: Contributor Workflow

1. Fork the repository and create a feature branch from main.
2. Make your change. Add or update tests in tests/ accordingly.
3. Commit using a Conventional Commits message. The pre-commit hook runs composer checks automatically.
4. Push and open a Pull Request against main.
5. All CI checks must pass before a merge is considered.
6. Maintainers review and merge.

---

Release Process

Releases are automated using symplify/monorepo-builder configured in monorepo-builder.php

Diagram: Release Worker Sequence

Workers are defined in monorepo-builder.php41-54 Run a dry run first to verify:

Then execute:

Sources: monorepo-builder.php41-56 composer.json371-379

---

Changelog Generation

CHANGELOG.md is generated by git-chglog (the UpdateChangelogViaGoReleaseWorker release worker invokes it). Configuration is at .chglog/config.yml and the template at .chglog/CHANGELOG.tpl.md

Diagram: Changelog Pipeline

Key configuration in .chglog/config.yml10-21:

• Commits are sorted by Scope
• Groups are sorted by a custom title_order (feat → fix → docs → style → refactor → …)
• chore type is explicitly excluded from the filter
• BREAKING CHANGE notes are extracted as a separate section

The CHANGELOG.md file uses a merge=union git attribute (.gitattributes18-19) to avoid merge conflicts.

Sources: .chglog/config.yml1-76 .chglog/CHANGELOG.tpl.md1-63 .gitattributes18-19

---

Code of Conduct

All participants are expected to follow the project's Code of Conduct at .github/CODE_OF_CONDUCT.md Violations can be reported to ityaozm@gmail.com. The code of conduct is based on the Contributor Covenant v2.0.

Sources: .github/CODE_OF_CONDUCT.md1-129

---

What Gets Excluded from Archives

Files that are irrelevant to end users are excluded from git archive exports via .gitattributes export-ignore rules .gitattributes36-63 This includes:

• All dotfiles and configuration (/.*/, /*.neon, /.php-cs-fixer.*)
• /tests/, /vendor-bin/, /vendor/, /benchmarks/
• rector.php, monorepo-builder.php, CHANGELOG*.md

Source distributions do not contain development tooling.

Sources: .gitattributes36-63