Skip to content

Commit 0d7f0d3

Browse files
JoshuaEstesJoshuaEstes
authored
Merge branch 'main' into chorale
2 parents 3f26ecb + 4c274d8 commit 0d7f0d3

52 files changed

Lines changed: 842 additions & 3 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,64 @@
1-
# AGENTS
1+
# Agents Guide for Sons of PHP Monorepo
22

3-
This repository contains multiple projects and tools that are maintained here.
3+
This repository is a PHP monorepo containing many packages under `src/`. This guide provides consistent instructions for AI coding agents to work safely and effectively across the codebase.
44

55
- Use clear variable names and keep code well documented.
66
- Run tests relevant to the areas you change.
77
- For changes under `tools/chorale`, run `composer install` and `./vendor/bin/phpunit` in that directory before committing.
88
- Chorale is the monorepo management CLI using a plan/apply workflow; see `tools/chorale/AGENTS.md` for its roadmap and guidelines.
99

10+
## Repo Layout
11+
12+
- Root: build tooling (`Makefile`, composer), shared configs, CI inputs.
13+
- Code: packages live under `src/SonsOfPHP/*`, typically with `src/` and `Tests/` subfolders.
14+
- Docs: developer documentation in `docs/` with a GitBook-style `SUMMARY.md`.
15+
- Tools: development tools vendored under `tools/` (phpunit, psalm, rector, php-cs-fixer, etc.).
16+
17+
## Ground Rules
18+
19+
- Prefer minimal, targeted changes; avoid refactors beyond the task scope.
20+
- Never edit anything under any `vendor/` directory or generated artifacts like `dist/`.
21+
- Maintain backward compatibility for public APIs unless explicitly instructed otherwise.
22+
- Update relevant docs under `docs/` when behavior or public APIs change.
23+
- Keep code style consistent; use provided tooling to format, lint, and check types.
24+
25+
## Setup
26+
27+
- Install dependencies once at the repo root:
28+
- `make install`
29+
30+
## Common Tasks
31+
32+
- Run tests (entire repo):
33+
- `make test`
34+
- Run tests (limit to a package):
35+
- `PHPUNIT_OPTIONS='path/to/package/Tests' make test`
36+
- Code style (dry-run):
37+
- `make php-cs-fixer`
38+
- Static analysis (Psalm):
39+
- `make psalm`
40+
- Rector & style upgrades (may modify files):
41+
- `make upgrade-code`
42+
- Lint PHP syntax:
43+
- `make lint`
44+
- Coverage report:
45+
- `make coverage`
46+
47+
## When Editing a Package
48+
49+
- Work inside that package directory (e.g. `src/SonsOfPHP/Component/Clock`).
50+
- Put new source under that package’s `src/`; add tests under its `Tests/`.
51+
- Use the package-focused test command above to tighten feedback cycles.
52+
53+
## Documentation
54+
55+
- Update `docs/` to reflect user-facing changes.
56+
- Add or modify the most relevant page (e.g., `docs/components/*.md`, `docs/contracts/*.md`, or `docs/symfony-bundles/*.md`).
57+
- If adding a new page, ensure it’s listed in `docs/SUMMARY.md`.
58+
59+
## Pull Request Checklist
60+
61+
- Build passes: `make test` (optionally with coverage).
62+
- Code quality passes: `make php-cs-fixer`, `make psalm`, and (if applicable) `make upgrade-code`.
63+
- Docs updated where needed.
64+
- No changes to `vendor/` or generated artifacts.

‎docs/AGENTS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Agents Guide for Docs
2+
3+
This project’s documentation lives in `docs/` and is organized for GitBook consumption with a table of contents in `SUMMARY.md`.
4+
5+
## Principles
6+
7+
- Keep docs accurate, concise, and task-oriented.
8+
- Prefer small, incremental updates alongside code changes.
9+
- Mirror package names and concepts used in code for easy navigation.
10+
11+
## Where to Edit
12+
13+
- Components: `docs/components/*.md`
14+
- Contracts: `docs/contracts/*.md`
15+
- Symfony bundles: `docs/symfony-bundles/*.md`
16+
- Bard CLI: `docs/bard/*.md`
17+
- General/Project: `docs/README.md`, `docs/getting-help.md`, etc.
18+
19+
## Table of Contents
20+
21+
- When adding new pages, update `docs/SUMMARY.md` to include them in the navigation.
22+
23+
## Writing Style
24+
25+
- Use clear headings and short sections.
26+
- Include small code examples (PHP) when helpful.
27+
- Document public APIs and noteworthy behavior changes.
28+
- Link to related pages within `docs/` when context helps.
29+
30+
## Quick Checks
31+
32+
- Cross-check names, namespaces, and examples with the code.
33+
- Keep examples runnable where possible.
34+
- Avoid duplicating content that can be linked.
35+

‎src/SonsOfPHP/Bard/AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bard
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bard/src`
6+
- Tests: `src/SonsOfPHP/Bard/Tests`
7+
- Do not edit: `src/SonsOfPHP/Bard/vendor/`, `src/SonsOfPHP/Bard/dist/`
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bard/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Keep CLI outputs stable; update docs in `docs/bard/` if UX changes.
19+
- Avoid committing built artifacts under `dist/`.
20+

‎src/SonsOfPHP/Bridge/Aws/Filesystem/AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Aws/Filesystem
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Aws/Filesystem/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Aws/Filesystem/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Aws/Filesystem/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Ensure AWS-related integrations remain optional and well-typed.
19+
- If user-facing behavior changes, update related docs under `docs/components/` or integration sections as applicable.
20+

‎src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/AGENTS.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/Collections/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/Collections/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+
16+
## Notes
17+
18+
- Keep Doctrine-related integrations loosely coupled and optional.
19+

‎src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/DBAL/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

‎src/SonsOfPHP/Bridge/Doctrine/EventSourcing/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/EventSourcing
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/EventSourcing/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

‎src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Doctrine/ORM/Pager
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Doctrine/ORM/Pager/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

‎src/SonsOfPHP/Bridge/LiipImagine/Filesystem/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/LiipImagine/Filesystem
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/src`
6+
- Tests: `src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/LiipImagine/Filesystem/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

‎src/SonsOfPHP/Bridge/Symfony/Cqrs/AGENTS.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Agents Guide for Package: src/SonsOfPHP/Bridge/Symfony/Cqrs
2+
3+
## Scope
4+
5+
- Source: `src/SonsOfPHP/Bridge/Symfony/Cqrs/src`
6+
- Tests: `src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests`
7+
- Do not edit: any `vendor/` directories
8+
9+
## Workflows
10+
11+
- Install once at repo root: `make install`
12+
- Test this package only: `PHPUNIT_OPTIONS='src/SonsOfPHP/Bridge/Symfony/Cqrs/Tests' make test`
13+
- Style and static analysis: `make php-cs-fixer` and `make psalm`
14+
- Upgrade code (may modify files): `make upgrade-code`
15+

0 commit comments

Comments
 (0)