From 2fc636ddeafeb420b9b23c3ee37752baebf05aec Mon Sep 17 00:00:00 2001 From: Joshua Estes Date: Wed, 20 Aug 2025 00:43:36 -0400 Subject: [PATCH 1/2] docs: outline prioritized roadmap --- AGENTS.md | 5 +++++ ROADMAP.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 ROADMAP.md diff --git a/AGENTS.md b/AGENTS.md index a3b67200..f959205b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,6 +51,11 @@ This repository is a PHP monorepo containing many packages under `src/`. This gu - Add or modify the most relevant page (e.g., `docs/components/*.md`, `docs/contracts/*.md`, or `docs/symfony-bundles/*.md`). - If adding a new page, ensure it’s listed in `docs/SUMMARY.md`. +## Roadmap + +- The project roadmap lives in `ROADMAP.md` at the repository root. +- Remove completed items from the roadmap as part of the related change. + ## Pull Request Checklist - Build passes: `make test` (optionally with coverage). diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..a3529d78 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,63 @@ +# Sons of PHP Roadmap + +This roadmap outlines planned libraries and updates for the Sons of PHP monorepo. Completed items must be removed to keep the list current. + +## Global Definition of Ready +- Problem statement and goals are clearly documented. +- Scope, dependencies, and related packages are identified. +- Acceptance criteria and testing strategy are defined. +- Stakeholders have reviewed and approved the proposal. + +## Global Definition of Done +- Implementation meets the documented acceptance criteria. +- Unit and integration tests are added or updated and pass. +- Documentation reflects the new or changed behavior. +- `make test`, `make php-cs-fixer`, and `make psalm` pass. +- The corresponding roadmap entry is removed. + +## Prioritized Roadmap +1. **Stabilize Core Components for 1.0 Release** + - Finalize public APIs for existing components. + - Increase test coverage and fix outstanding issues. + - Prepare changelogs and migration guides. + - **Acceptance Criteria** + - Every component tagged for 1.0 has >=90% test coverage. + - Changelogs outline breaking changes and upgrade paths. + - Documentation updated for all stabilized components. + +2. **Update HTTP Libraries to Latest PSR Versions** + - Align `HttpMessage` and `HttpFactory` components with PSR-7 v2 and PSR-17 updates. + - Ensure compatibility with PSR-18 clients. + - **Acceptance Criteria** + - Components comply with PSR-7 v2 and PSR-17. + - Integration tests against a PSR-18 client pass. + - Docs include examples using the updated interfaces. + +3. **Introduce Validation Component** + - Provide a rule-based validation system similar to Symfony Validator but framework agnostic. + - Include common validators and an extensible API for custom rules. + - **Acceptance Criteria** + - New `Component/Validation` with rule definitions and error reporting. + - Unit tests cover each validator and failure scenario. + - Documentation with usage examples and customization guide. + +4. **Add Queue Component for Background Jobs** + - Implement a simple queue abstraction with in-memory and Redis adapters. + - Provide Symfony Messenger bridge for interoperability. + - **Acceptance Criteria** + - `Component/Queue` with enqueue/dequeue interfaces and adapters. + - Bridge package integrates with Symfony Messenger. + - Tests demonstrate reliable job processing and failure handling. + +5. **Enhance Symfony Bridges for Symfony 7** + - Review all Symfony bridge packages for compatibility with Symfony 7. + - Add support for new security and HTTP features where applicable. + - **Acceptance Criteria** + - Bridges pass tests against Symfony 7 components. + - Deprecated APIs removed and replacements documented. + - Release notes describe Symfony 7 compatibility. + +## Suggestions +- Automate dependency updates with a scheduled tool (e.g., Renovate or Dependabot). +- Establish coding style guides per component to encourage consistency. +- Consider setting up benchmarks for performance-critical components. From 5f2e8b47de37c59478ceb9659c0f208e58b48d5a Mon Sep 17 00:00:00 2001 From: Joshua Estes Date: Wed, 20 Aug 2025 01:03:40 -0400 Subject: [PATCH 2/2] docs: standardize roadmap --- AGENTS.md | 4 ++ ROADMAP.md | 147 ++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 111 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f959205b..ff79d778 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,10 @@ This repository is a PHP monorepo containing many packages under `src/`. This gu - The project roadmap lives in `ROADMAP.md` at the repository root. - Remove completed items from the roadmap as part of the related change. +- Each roadmap entry is an epic with a name and short description. +- Every epic lists the tasks required to complete it. +- Each task includes its own acceptance criteria and references the Global Definition of Ready and Definition of Done. +- Remove tasks once complete and delete the epic when no tasks remain. ## Pull Request Checklist diff --git a/ROADMAP.md b/ROADMAP.md index a3529d78..ca629ab5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -15,49 +15,116 @@ This roadmap outlines planned libraries and updates for the Sons of PHP monorepo - `make test`, `make php-cs-fixer`, and `make psalm` pass. - The corresponding roadmap entry is removed. +## How to Use This Roadmap + +- Each entry below is an **epic** with a name and short description. +- Epics contain a list of tasks. Every task must: + - satisfy the [Global Definition of Ready](#global-definition-of-ready) before work begins; + - meet the [Global Definition of Done](#global-definition-of-done) on completion; and + - define its own acceptance criteria. +- Remove tasks as they are completed. +- When an epic has no remaining tasks, remove the epic. + ## Prioritized Roadmap -1. **Stabilize Core Components for 1.0 Release** - - Finalize public APIs for existing components. - - Increase test coverage and fix outstanding issues. - - Prepare changelogs and migration guides. - - **Acceptance Criteria** - - Every component tagged for 1.0 has >=90% test coverage. - - Changelogs outline breaking changes and upgrade paths. - - Documentation updated for all stabilized components. - -2. **Update HTTP Libraries to Latest PSR Versions** - - Align `HttpMessage` and `HttpFactory` components with PSR-7 v2 and PSR-17 updates. - - Ensure compatibility with PSR-18 clients. - - **Acceptance Criteria** - - Components comply with PSR-7 v2 and PSR-17. - - Integration tests against a PSR-18 client pass. - - Docs include examples using the updated interfaces. - -3. **Introduce Validation Component** - - Provide a rule-based validation system similar to Symfony Validator but framework agnostic. - - Include common validators and an extensible API for custom rules. - - **Acceptance Criteria** - - New `Component/Validation` with rule definitions and error reporting. - - Unit tests cover each validator and failure scenario. - - Documentation with usage examples and customization guide. - -4. **Add Queue Component for Background Jobs** - - Implement a simple queue abstraction with in-memory and Redis adapters. - - Provide Symfony Messenger bridge for interoperability. - - **Acceptance Criteria** - - `Component/Queue` with enqueue/dequeue interfaces and adapters. - - Bridge package integrates with Symfony Messenger. - - Tests demonstrate reliable job processing and failure handling. - -5. **Enhance Symfony Bridges for Symfony 7** - - Review all Symfony bridge packages for compatibility with Symfony 7. - - Add support for new security and HTTP features where applicable. - - **Acceptance Criteria** - - Bridges pass tests against Symfony 7 components. - - Deprecated APIs removed and replacements documented. - - Release notes describe Symfony 7 compatibility. + +### Epic: Stabilize Core Components for 1.0 Release +**Description:** Finalize public APIs, increase test coverage, and prepare documentation for a stable 1.0 release. + +- [ ] Finalize public APIs for existing components. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Public APIs are documented and approved. + - Implementation meets the Global DoD. +- [ ] Increase test coverage and fix outstanding issues. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Components tagged for 1.0 reach at least 90% test coverage. + - All known issues are resolved. + - Implementation meets the Global DoD. +- [ ] Prepare changelogs and migration guides. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Changelogs outline breaking changes and upgrade paths. + - Migration guides are published. + - Implementation meets the Global DoD. + +### Epic: Update HTTP Libraries to Latest PSR Versions +**Description:** Align HTTP components with the latest PSR standards and ensure client compatibility. + +- [ ] Align `HttpMessage` and `HttpFactory` with PSR-7 v2 and PSR-17. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Components comply with PSR-7 v2 and PSR-17. + - Implementation meets the Global DoD. +- [ ] Ensure compatibility with PSR-18 clients. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Integration tests against a PSR-18 client pass. + - Implementation meets the Global DoD. +- [ ] Update documentation with examples for the updated interfaces. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Docs include examples using the updated interfaces. + - Implementation meets the Global DoD. + +### Epic: Introduce Validation Component +**Description:** Provide a framework-agnostic, rule-based validation system with extensible APIs. + +- [ ] Implement `Component/Validation` with rule definitions and error reporting. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Component exposes an extensible API for custom rules. + - Implementation meets the Global DoD. +- [ ] Add unit tests covering each validator and failure scenario. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Tests cover common validators and edge cases. + - Implementation meets the Global DoD. +- [ ] Document usage examples and customization guides. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Documentation explains basic usage and extension points. + - Implementation meets the Global DoD. + +### Epic: Add Queue Component for Background Jobs +**Description:** Implement a queue abstraction with adapters and a Symfony Messenger bridge. + +- [ ] Implement queue abstraction with in-memory and Redis adapters. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - `Component/Queue` provides enqueue/dequeue interfaces and adapters. + - Tests demonstrate reliable job processing and failure handling. + - Implementation meets the Global DoD. +- [ ] Provide Symfony Messenger bridge for interoperability. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Bridge integrates with Symfony Messenger. + - Implementation meets the Global DoD. + +### Epic: Enhance Symfony Bridges for Symfony 7 +**Description:** Review bridge packages for Symfony 7 compatibility and add support for new features. + +- [ ] Review and update bridge packages for Symfony 7 compatibility. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Bridges pass tests against Symfony 7 components. + - Implementation meets the Global DoD. +- [ ] Remove deprecated APIs and document replacements. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Deprecated APIs are removed. + - Docs describe new APIs and migration paths. + - Implementation meets the Global DoD. +- [ ] Document release notes describing Symfony 7 compatibility. + - **Acceptance Criteria** + - All Global DoR items are satisfied before implementation begins. + - Release notes highlight Symfony 7 support. + - Implementation meets the Global DoD. ## Suggestions + - Automate dependency updates with a scheduled tool (e.g., Renovate or Dependabot). - Establish coding style guides per component to encourage consistency. - Consider setting up benchmarks for performance-critical components. +- Link epics and tasks to issue trackers for traceability. +- Review roadmap items quarterly to keep priorities current.