From 28c6f1d12e0151bc240a80f9425759c6c037d3ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Say=C3=A3o=20Lobato=20Abreu?= Date: Mon, 26 Oct 2026 18:08:18 -0300 Subject: [PATCH 1/2] docs: align package README with verified contracts --- .changelog/package-readme.md | 7 +++ README.md | 109 ++++++++++++++++++++++++++++++++++- 2 files changed, 113 insertions(+), 3 deletions(-) create mode 100644 .changelog/package-readme.md diff --git a/.changelog/package-readme.md b/.changelog/package-readme.md new file mode 100644 index 0000000..425c91a --- /dev/null +++ b/.changelog/package-readme.md @@ -0,0 +1,7 @@ +--- +category: changed +type: patch +pull_request: 34 +--- + +Organize the README around verified installation, commands, configuration, integration and compatibility, with source-backed badges, API summary and contributor guidance. diff --git a/README.md b/README.md index f690a8d..e54171c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,25 @@ # Fast Forward Code Standards +[![PHP](https://img.shields.io/badge/php-%5E8.3-777BB4?logo=php&logoColor=white)](composer.json) +[![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/code-standards/repository-ci.yml?branch=main&label=tests)](https://github.com/php-fast-forward/code-standards/actions/workflows/repository-ci.yml) +[![Docs](https://img.shields.io/badge/docs-source-38BDF8)](docs/architecture.md) +[![License](https://img.shields.io/github/license/php-fast-forward/code-standards?color=64748B)](LICENSE) +[![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?color=EC4899)](https://github.com/sponsors/php-fast-forward) + Focused PHP style and static syntax checks, independent of DevTools. The library provides an extendable ECS PSR-12 preset; the CLI checks tracked PHP files or the files changed by an exact PR head. This initial increment validates PHP syntax and style, not type correctness, application behavior or coverage. -## Local development and first adoption +## ✨ Features + +- Native ECS configuration with consumer overrides applied last. +- Read-only syntax/style checking and explicitly requested local fixes. +- Exact PR merge-base selection with binary-safe file paths. +- Invocable Symfony Console commands composed with Fast Forward Container. +- An unprivileged reusable workflow and a portable consumption skill. + +## 📦 Installation and requirements Requires PHP 8.3+, Git and Composer runtime API 2.2+ for installed binary proxies. Composer resolves the tool runtime independently from @@ -23,6 +37,8 @@ and activation are explicit. The development `check` script validates Composer metadata and the actual platform before running this package's tests and style check. Operational channel dependencies remain development-only. +For a reviewed source checkout: + ```sh composer install --no-plugins --no-scripts php bin/code-standards help @@ -32,6 +48,8 @@ php bin/code-standards fix --all composer test ``` +## 🛠️ Usage + `check` reports violations with a nonzero status and does not change source. The default preset stores its ECS cache beneath the system temporary directory, in `fast-forward-code-standards/`. @@ -53,7 +71,7 @@ Symfony Console provides `help check`, standard global flags and both `--option=value` and `--option value`. Error diagnostics use stderr. Empty paths, conflicting scan modes and unsupported arguments are rejected explicitly. -### Library and local configuration +## ⚙️ Configuration and extension Once a reviewed version/ref is available, install `fast-forward/code-standards` as development tooling. No release of this package is assumed by these examples. @@ -87,7 +105,7 @@ both ECS and a competing PHP-CS-Fixer pass. Standalone ECS users may import the same library preset and set their own paths. CLI selection uses the scope below; ECS's configured paths do not expand the CLI's explicit selected file list. -## File scope and guarantees +## 🔌 Integration and file scope - Tracked `*.php` and PHP entrypoints under `bin/` are included. - `vendor`, `.git`, `.build`, `.dev-tools`, `backup`, `cache`, `public`, @@ -106,3 +124,88 @@ The [architecture decision](docs/architecture.md) defines library/tool dependenc directions and CPX/autoload limits. Rector/custom PHPDoc transformations and deeper static analysis are separate, unimplemented increments; this package does not assert extraction parity yet. + +## 🧰 API summary + +| Entry point | Contract | +| --- | --- | +| `code-standards check` | Parse selected PHP and check style without changing source. | +| `code-standards fix` | Explicitly format selected source, then verify; failures may leave partial changes. | +| `ECSConfig::configure(?callable $customize)` | Return the native ECS builder; apply the optional callback last. | +| `help check` / `help fix` | Show the installed Symfony option definitions. | + +Internal CLI services are implementation details. Supported configuration uses +native ECS rule imports, skips and configured rules; there is no second DSL. + +## 📁 Package layout + +```text +bin/code-standards CLI entrypoint +config/ecs.php default native ECS configuration +src/Config/ECSConfig.php reusable preset API +resources/skills/fast-forward-code-standards/ canonical consumer skill +resources/workflows/code-standards.yml consumer workflow wrapper +.github/actions/check/ small check adapter +docs/ architecture, policy and integration guides +``` + +## 🛠️ Versioning and compatibility + +Development releases stay in `0.x`. A compatible correction uses a patch; +functionality and breaking development changes use a minor. Changelog automation +prepares and publishes versions through reviewed PRs. Verify actual +[releases](https://github.com/php-fast-forward/code-standards/releases) before +selecting a Composer constraint. The GitHub `v0` channel is created only after a +verified publication and can advance across development minors; it is not a +Composer `^0.1` constraint. + +## ❓ FAQ + +**Can I use this as a staged-only pre-commit check?** +The CLI selects working-tree files from Git, not staged index blobs. Changed +mode requires a clean tracked checkout and cannot certify staged-only content. + +**Does it run PHPStan, Rector or my application's tests?** +No. This increment checks syntax and style. Type analysis, semantic refactoring +and application testing have separate scopes and compatibility requirements. + +**Does a successful first fix always mean the source is clean?** +The CLI verifies each formatted batch and reports remaining violations. Rules +can interact across passes; inspect the diff before explicitly fixing again. + +**Where do agent skills come from?** +The canonical payload is under `resources/skills`, advertised by +`extra.skills.source`. Consumers may explicitly select the optional LLM Skills manager. This package +does not provide another installer, activate skills or migrate consumer settings. +The DevTools README/Sphinx authoring skills were read as references and were not +imported into this repository. + +## 🛡️ License + +[MIT](LICENSE). Dash artwork follows the PHP Fast Forward brand references; +the upstream [artwork provenance record](https://github.com/php-fast-forward/.github/blob/v0.3.0/docs/brand/artwork-rights.md) +records its generative origin and historical rights limits separately. + +## 🤝 Contributing + +Read [AGENTS.md](AGENTS.md), add a focused regression and a unique `.changelog` +fragment, then open a scoped PR. Preserve check's source/lock no-write guarantee. + +```sh +composer install --no-plugins --no-scripts +composer check +``` + +Workflow contributor checks also need Bash and jq. Changes use normal current-head +CI and review gates; this guide does not authorize release, security-setting +changes or consumer rollout. + +## 🔗 Links + +- [Repository](https://github.com/php-fast-forward/code-standards) +- [Issues](https://github.com/php-fast-forward/code-standards/issues) +- [Composer package metadata](composer.json) +- [Automation and consumer refs](docs/automation.md) +- [Policy and differences](docs/policy.md) +- [Fast Forward Container](https://github.com/php-fast-forward/container) +- [Changelog](https://github.com/php-fast-forward/changelog) From 15a17b3e9cb35a1fc3bbbf5a3fa8e70875315b49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felipe=20Say=C3=A3o=20Lobato=20Abreu?= Date: Mon, 26 Oct 2026 19:06:12 -0300 Subject: [PATCH 2/2] docs: describe verified published Composer installation --- README.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e54171c..ab01867 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Fast Forward Code Standards [![PHP](https://img.shields.io/badge/php-%5E8.3-777BB4?logo=php&logoColor=white)](composer.json) +[![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fcode--standards-F28D1A?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/code-standards) [![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/code-standards/repository-ci.yml?branch=main&label=tests)](https://github.com/php-fast-forward/code-standards/actions/workflows/repository-ci.yml) [![Docs](https://img.shields.io/badge/docs-source-38BDF8)](docs/architecture.md) [![License](https://img.shields.io/github/license/php-fast-forward/code-standards?color=64748B)](LICENSE) @@ -21,6 +22,17 @@ style, not type correctness, application behavior or coverage. ## 📦 Installation and requirements +Install the published development tool in your Git project: + +```sh +composer require --dev fast-forward/code-standards:^0.1 --no-plugins --no-scripts +vendor/bin/code-standards check --all +``` + +The verified first release is `v0.1.0`; select a compatible version deliberately. +The separate GitHub `v0` workflow channel can advance across development minors. + + Requires PHP 8.3+, Git and Composer runtime API 2.2+ for installed binary proxies. Composer resolves the tool runtime independently from the consumer application's PHP minimum; syntax is checked using the executing @@ -73,11 +85,11 @@ conflicting scan modes and unsupported arguments are rejected explicitly. ## ⚙️ Configuration and extension -Once a reviewed version/ref is available, install `fast-forward/code-standards` -as development tooling. No release of this package is assumed by these examples. -To trial before publication, use a Composer path repository pointing at this -checkout, require `*@dev`, and disable plugins/scripts. Production adoption must -select the reviewed Composer version and workflow/runtime refs together. +Install `fast-forward/code-standards` as development tooling. Select the reviewed +Composer version and workflow/runtime refs independently and deliberately. For +an isolated source trial, a local Composer path repository may require `*@dev` +with plugins/scripts disabled; that constraint describes the checkout, not a +published release. ```php