diff --git a/CHANGELOG.md b/CHANGELOG.md index 9838cd2..7271a96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,10 +2,12 @@ ## 0.2.1 Under development +- Bug #121: Update command syntax in `development.md` and `testing.md` for clarity and consistency (@terabytesoftw) + ## 0.2.0 January 24, 2024 - Enh #87: Refactor `SemverUtil::class` stability normalization logic (@terabytesoftw) -- Bug #104: Add support for PHP 8.4 (@terabytesoftw) +- Bug #104: Update nullable type hints for method parameters and properties for PHP 8.4 deprecated RFC nullable (@terabytesoftw) - Enh #105: Update dependencies in `composer.lock` (@terabytesoftw) - Enh #106: Update composer dependencies for compatibility with newer versions (@terabytesoftw) - Bug #107: Force 4-space indentation when updating `package.json` (@terabytesoftw) @@ -25,8 +27,8 @@ ## 0.1.2 June 10, 2024 -- Bug #64: Update docs, `composer.lock` and change directory in `Solver.php` (@terabytesoftw) -- Enh #63: Add the ability to specify a custom directory for `package.json` (@terabytesoftw) +- Bug #64: Update docs, `composer.lock` and directory in `Solver.php` (@terabytesoftw) +- Enh #66: Add the ability to specify a custom directory for assets (@terabytesoftw) - Bug #69: Add `funding.yml` file (@terabytesoftw) ## 0.1.1 April 4, 2024 @@ -36,4 +38,4 @@ ## 0.1.0 January 21, 2024 -- Initial release. +- Enh #1: Initial commit (@terabytesoftw) diff --git a/README.md b/README.md index 94529bb..46ba1f2 100644 --- a/README.md +++ b/README.md @@ -105,14 +105,13 @@ Composer state preserved if the install fails. ## Documentation -- [Guide](resources/doc/index.md) -- [Usage](resources/doc/usage.md) -- [Configuration](resources/doc/config.md) -- [Events](resources/doc/events.md) -- [FAQs](resources/doc/faqs.md) -- [Development Guide](docs/development.md) -- [Testing Guide](docs/testing.md) -- [Release Notes](https://github.com/php-forge/foxy/releases) +- ๐Ÿ“š [Guide](resources/doc/index.md) +- ๐Ÿ’ก [Usage](resources/doc/usage.md) +- โš™๏ธ [Configuration](resources/doc/config.md) +- ๐Ÿ“… [Events](resources/doc/events.md) +- โ“ [FAQs](resources/doc/faqs.md) +- ๐Ÿงช [Testing Guide](docs/testing.md) +- ๐Ÿ› ๏ธ [Development Guide](docs/development.md) ## Package information diff --git a/composer.json b/composer.json index 5d62a6b..d0ca562 100644 --- a/composer.json +++ b/composer.json @@ -80,6 +80,7 @@ "curl -fsSL -o .editorconfig https://raw.githubusercontent.com/yii2-extensions/template/main/.editorconfig", "curl -fsSL -o .gitattributes https://raw.githubusercontent.com/yii2-extensions/template/main/.gitattributes", "curl -fsSL -o .gitignore https://raw.githubusercontent.com/yii2-extensions/template/main/.gitignore", + "curl -fsSL -o .styleci.yml https://raw.githubusercontent.com/yii2-extensions/template/main/.styleci.yml", "curl -fsSL -o infection.json5 https://raw.githubusercontent.com/yii2-extensions/template/main/infection.json5", "curl -fsSL -o phpstan.neon https://raw.githubusercontent.com/yii2-extensions/template/main/phpstan.neon", "curl -fsSL -o phpunit.xml.dist https://raw.githubusercontent.com/yii2-extensions/template/main/phpunit.xml.dist" diff --git a/docs/development.md b/docs/development.md index 4897c34..0e75489 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,27 +1,42 @@ # Development -This document describes development workflows and maintenance tasks for this repository. +This document describes development workflows and maintenance tasks for the project. -## Local setup +## Sync Metadata -Install dependencies: +To keep configuration files synchronized with the latest template updates, use the `sync-metadata` command. This command +downloads the latest configuration files from the template repository. ```bash -composer install +composer sync-metadata ``` -## Project scripts +### Updated Files -The project exposes a small set of Composer scripts for validation. +This command updates the following configuration files: -| Script | Command | Purpose | -| ---------------------- | ----------------------------------- | ------------------------------------ | -| `test` | `composer run test` | Run the PHPUnit test suite | -| `psalm` | `composer run psalm` | Run static analysis | -| `easy-coding-standard` | `composer run easy-coding-standard` | Run ECS coding standards | -| `check-dependencies` | `composer run check-dependencies` | Verify declared runtime dependencies | +| File | Purpose | +| ------------------ | -------------------------------------------- | +| `.editorconfig` | Editor settings and code style configuration | +| `.gitattributes` | Git attributes and file handling rules | +| `.gitignore` | Git ignore patterns and exclusions | +| `.styleci.yml` | StyleCI code style analysis configuration | +| `infection.json5` | Infection mutation testing configuration | +| `phpstan.neon` | PHPStan static analysis configuration | +| `phpunit.xml.dist` | PHPUnit test configuration | -## Notes +### When to Run -- Keep changes minimal and consistent with existing code and behavior. -- Documentation and code comments are English-only. +Run this command in the following scenarios: + +- **Periodic Updates** - Monthly or quarterly to benefit from template improvements. +- **After Template Updates** - When the template repository has new configuration improvements. +- **Before Major Releases** - Ensure your project uses the latest best practices. +- **When Issues Occur** - If configuration files become outdated or incompatible. + +### Important Notes + +- This command overwrites existing configuration files with the latest versions from the template. +- Ensure you have committed any custom configuration changes before running this command. +- Review the updated files after syncing to ensure they work with your specific project needs. +- Some projects may require customizations after syncing configuration files. diff --git a/docs/testing.md b/docs/testing.md index 1fe32cf..e0e9d88 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,20 +1,30 @@ # Testing -This package provides a consistent set of Composer scripts for local validation. +This package provides a consistent set of [Composer](https://getcomposer.org/) scripts for local validation. Tool references: - [Composer Require Checker](https://github.com/maglnet/ComposerRequireChecker) for dependency definition checks. - [Easy Coding Standard (ECS)](https://github.com/easy-coding-standard/easy-coding-standard) for coding standards. -- [Psalm](https://psalm.dev/) for static analysis. +- [Infection](https://infection.github.io/) for mutation testing. +- [PHPStan](https://phpstan.org/) for static analysis. - [PHPUnit](https://phpunit.de/) for unit tests. +- [Rector](https://github.com/rectorphp/rector) for automated refactoring. + +## Automated refactoring (Rector) + +Run Rector to apply automated code refactoring. + +```bash +composer rector +``` ## Coding standards (ECS) Run Easy Coding Standard (ECS) and apply fixes. ```bash -composer run easy-coding-standard +composer ecs ``` ## Dependency definition check @@ -22,15 +32,29 @@ composer run easy-coding-standard Verify that runtime dependencies are correctly declared in `composer.json`. ```bash -composer run check-dependencies +composer check-dependencies +``` + +## Mutation testing (Infection) + +Run mutation testing. + +```bash +composer mutation +``` + +Run mutation testing with static analysis enabled. + +```bash +composer mutation-static ``` -## Static analysis (Psalm) +## Static analysis (PHPStan) Run static analysis. ```bash -composer run psalm +composer static ``` ## Unit tests (PHPUnit) @@ -38,21 +62,21 @@ composer run psalm Run the full test suite. ```bash -composer run test +composer tests ``` ## Passing extra arguments Composer scripts support forwarding additional arguments using `--`. -Example: run a specific PHPUnit test or filter by name. +Run PHPUnit with code coverage report generation. ```bash -composer run test -- --filter AssetManagerTest +composer tests -- --coverage-html code_coverage ``` -Example: run Psalm with a different memory limit. +Run PHPStan with a different memory limit. ```bash -composer run psalm -- --memory-limit=512M +composer static -- --memory-limit=512M ```