From 4bf5c596ee1fc0451bf82ab8ad204d4ca9e10a31 Mon Sep 17 00:00:00 2001 From: "andre.soares" Date: Thu, 2 Jul 2026 18:01:34 +0100 Subject: [PATCH] docs: add kun-init 4-file documentation structure --- AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 50 +++++++++++++++++++++++++++++++++++++++------- README.md | 28 ++------------------------ 4 files changed, 99 insertions(+), 33 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..60e6bb3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,53 @@ +# AGENTS.md + +Steering notes for AI agents working in this repository. For install and usage see [README.md](README.md); for development setup, testing, and the contribution process see [CONTRIBUTING.md](CONTRIBUTING.md). + +## What This Is + +`kununu/collections` is a PHP library that reduces the boilerplate involved in building typed collections on top of `ArrayIterator`. It is consumed as a Composer package (`composer require kununu/collections`) and has no runtime application, service, or deployment. + +## Domain + +The library provides interfaces, traits, and abstract base classes for: + +- Collections backed by `ArrayIterator` (basic and filterable). +- Converting collection items to and from `array`, `string`, `int`, and `Stringable`. +- Comparing collection items. +- Filtering and grouping collection data. +- Key/value structures, including enum-keyed variants. +- Building items and mapping between representations. + +## Code Layout + +- `src/` — library source, PSR-4 under `Kununu\Collection\`. + - `Convertible/`, `Comparable/` — conversion and comparison interfaces. + - `Filter/` — filtering and grouping primitives. + - `EnumKeyValue/` — enum-keyed key/value support and its exceptions. + - `AbstractItemBuilderTraits/`, `Mapper/`, `Helper/`, `Exception/` — item builders, mapping, helpers, and exceptions. + - `TestCase/` — `AbstractCollectionTestCase` for consumers testing their own collections. +- `tests/` — PHPUnit tests, PSR-4 under `Kununu\Collection\Tests\`. +- `docs/` — per-feature documentation referenced from the README. + +## Quality Gates + +All of the following must pass. Run them via the Composer scripts: + +- `composer cs` — PHP CS Fixer (kununu coding standards). +- `composer sniffer` — PHP_CodeSniffer. +- `composer phpstan` — PHPStan. +- `composer rector` — Rector (dry-run). +- `composer test` — PHPUnit. + +See the `scripts` section of `composer.json` for the complete list. + +## Hard Constraints + +- The PHP version is pinned in `composer.json` (`require.php`); do not lower it. +- Keep the public API stable. This library follows semantic versioning; API changes require a corresponding `CHANGELOG.md` entry. +- Every code change must be covered by tests. +- Respect the existing coding standards; do not bypass the quality gates. +- Runtime code may depend only on PHP and `ext-mbstring`; keep other tooling in `require-dev`. + +## Deep Documentation + +Feature-level details live in `docs/` (collection interfaces, traits, convertibles, mappers, key/value, and the test case). Start from the links in [README.md](README.md). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 519e52b..e66f71e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,20 +4,56 @@ Contributions are more than **welcome**. We accept contributions via Pull Requests on [GitHub](https://github.com/kununu/collections). +## Development Setup + +Install the dependencies: + +```bash +composer install +``` + +The required PHP version is pinned in `composer.json` (`require.php`). Development tooling (PHPUnit, PHPStan, Rector, and the kununu coding standards) is installed as dev dependencies. + +## Testing + +Run the test suite: + +```bash +composer test +``` + +Run the tests with a coverage report: + +```bash +composer test-coverage +``` + +## Quality Gates + +The following checks run in CI and must pass before a pull request can be merged. They can be run locally through the corresponding Composer scripts: + +- `composer cs` — PHP CS Fixer with the kununu coding standards +- `composer sniffer` — PHP_CodeSniffer (`composer sniffer-fix` to auto-fix) +- `composer phpstan` — PHPStan static analysis +- `composer rector` — Rector in dry-run mode (`composer rector-fix` to apply) +- `composer test` — PHPUnit test suite + +See the `scripts` section of `composer.json` for the full list. CI additionally runs `composer-dependency-analyser`, `composer-require-checker`, and `composer-normalize`. + ## Pull Requests -- **[kununu Coding Standards](https://github.com/kununu/code-tools)** - The kununu coding standards are an extension of the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md). Check out [kununu Coding Standards](https://github.com/kununu/code-tools) for more details. In development mode the package [kununu/code-tools](https://github.com/kununu/code-tools) is already a dependency that expose commands that you can use to meet our standards. +- **[kununu Coding Standards](https://github.com/kununu/code-tools)** — The kununu coding standards are an extension of the [PSR-2](https://github.com/php-fig/fig-standards/blob/main/accepted/PSR-2-coding-style-guide.md). The [kununu/code-tools](https://github.com/kununu/code-tools) package is already a dev dependency and exposes the commands you need to meet our standards. -- **Add tests!** - to ensure a high quality code base, your code patch can't be accepted if it does not have tests. +- **Add tests!** — To ensure a high quality code base, your code patch can't be accepted if it does not have tests. -- **Document any change in behaviour** - Make sure the `CHANGELOG.md`, `README.md` and any other relevant documentation are kept up-to-date. +- **Document any change in behaviour** — Make sure the `CHANGELOG.md`, `README.md`, and any other relevant documentation are kept up-to-date. -- **Consider our release cycle** - Since we're using semantic versioning ([SemVer v2.0.0](http://semver.org/)). Changes to the API must be done with great consideration, and prevented if at all possible. +- **Consider our release cycle** — We use semantic versioning ([SemVer v2.0.0](https://semver.org/)). Changes to the API must be done with great consideration, and prevented if at all possible. -- **Create feature branches** - Master is the stable branch, create a new branch for each feature. +- **Create feature branches** — `main` is the stable branch, create a new branch for each feature. -- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests. +- **One pull request per feature** — If you want to do more than one thing, send multiple pull requests. -- **Be respectful** - Be excellent to other contributors. See our [Code of Conduct](CODE_OF_CONDUCT.md). +- **Be respectful** — Be excellent to other contributors. See our [Code of Conduct](CODE_OF_CONDUCT.md). **Happy coding**! diff --git a/README.md b/README.md index ea3d020..68f506a 100644 --- a/README.md +++ b/README.md @@ -10,29 +10,6 @@ You can use this library by issuing the following command: composer require kununu/collections ``` -## Running Tests - -Run the tests by doing: - -```bash -composer install -vendor/bin/phpunit -``` - -or - -```bash -composer install -composer test -``` - -To run test and generate coverage information: - -```bash -composer install -composer test-coverage -``` - ## Usage The library defines interfaces to deal with collections and also boilerplate code with default implementations. @@ -61,12 +38,11 @@ More details: See [CHANGELOG.md](CHANGELOG.md) for the list of notable changes in each release. -## Contribute +## Contributing -If you are interested in contributing read our [contributing guidelines](/CONTRIBUTING.md). +If you are interested in contributing read our [contributing guidelines](CONTRIBUTING.md). ------------------------------ ![Continuous Integration](https://github.com/kununu/collections/actions/workflows/continuous-integration.yml/badge.svg) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kununu_collections&metric=alert_status)](https://sonarcloud.io/dashboard?id=kununu_collections) -