From 1d20d817e6277c0e21a1cf6657452ea771a1b71f Mon Sep 17 00:00:00 2001 From: pradeepkch6-ai Date: Sat, 15 Aug 2026 02:47:31 +0500 Subject: [PATCH] docs: Overhaul contributor infrastructure and add GitHub templates - Expands CONTRIBUTING.md with setup, code style (ECS), static analysis (PHPStan), and testing instructions derived from composer.json. - Preserves the existing regression-corpus contract documentation. - Adds .github/ISSUE_TEMPLATE for bug reports and feature requests. - Adds .github/PULL_REQUEST_TEMPLATE.md with a CI-aligned checklist. --- .github/ISSUE_TEMPLATE/bug_report.md | 29 +++++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 +++++ .github/PULL_REQUEST_TEMPLATE.md | 29 +++++++ CONTRIBUTING.md | 92 +++++++++++++++++++---- 4 files changed, 156 insertions(+), 14 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..3f84c0a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug Report +about: Create a report to help us improve Durable Workflow +title: "[Bug] " +labels: bug +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Define workflow '...' +2. Start execution with payload '...' +3. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Environment:** + - PHP Version: [e.g. 8.1] + - Laravel Version: [e.g. 10.0] + - Durable Workflow Version: [e.g. v2.0.0-rc.31] + - OS: [e.g. Ubuntu] + +**Additional context** +Add any other context about the problem here, such as stack traces or logs. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..dc330e4e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: "[Feature] " +labels: enhancement +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..7fb153e6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,29 @@ +## Description + + + +Fixes # (issue) + +## Type of change +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update + +## How Has This Been Tested? + + + +- [ ] `composer test` +- [ ] `composer stan` (PHPStan) +- [ ] `composer ecs` (Code Style) + +## Checklist: +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] If this touches replay/payload-codec logic, I have updated regression-corpus fixtures diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c0745e2..faa3f756 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,84 @@ -# Contributing +# Contributing to Durable Workflow -Run ECS in check mode, PHPStan, and focused PHPUnit coverage for changed code. +First off, thank you for considering contributing to Durable Workflow! It's people like you that make this engine a great tool for the Laravel community. -Replay and payload-codec fixes also follow the organization -[regression-corpus contract](https://github.com/durable-workflow/.github/tree/main/regression-corpus). -Use one-case golden histories under `tests/Fixtures/V2/GoldenHistory/` whenever -the query-state replay runner can consume them. Cold worker replay evidence -belongs under `tests/Fixtures/V2/ReplayRegression/`; each fixture names an -autoloadable workflow and is executed through the production -`WorkflowFiberRunner` using either persisted history or a worker command -sequence. Shared codec evidence belongs under `tests/Fixtures/V2/CodecRegression/` -and in every applicable official binding. +## Development Environment Setup -Fixtures preserve protocol version, value and type, framing, and stable failure -policy. Existing evidence is append-only. Run: +To set up the project locally: + +1. **Clone the repository:** + ```bash + git clone https://github.com/durable-workflow/workflow.git + cd workflow + ``` + +2. **Install dependencies:** + Make sure you have PHP 8.1+ and Composer installed. + ```bash + composer install + ``` + +3. **Set up the Testbench environment:** + We use Orchestra Testbench for our testing environment. + ```bash + composer prepare + composer build + ``` + +## Development Workflow + +### Code Style & Static Analysis + +We enforce strict coding standards using EasyCodingStandard (ECS) and PHPStan. Before submitting a PR, always run: ```bash -python scripts/ci/validate-regression-corpus.py --base-ref +# Check and automatically fix code style issues +composer ecs + +# Run static analysis +composer stan +# Alternatively, to run with verbose output: +composer lint ``` + +### Testing + +Tests are written using PHPUnit. Ensure your changes pass existing tests and include new ones if you're adding functionality. + +```bash +# Run the entire test suite +composer test + +# Run only unit tests +composer unit + +# Run only feature tests +composer feature + +# Generate coverage report (requires Xdebug) +composer coverage +``` + +## Regression Corpus & Fixtures + +**Important:** Replay and payload-codec fixes must follow the [regression-corpus contract](https://github.com/durable-workflow/.github/tree/main/regression-corpus). + +When working with worker replay or shared codecs, adhere to the following rules: + +1. Use one-case golden histories under `tests/Fixtures/V2/GoldenHistory/` whenever the query-state replay runner can consume them. +2. Cold worker replay evidence belongs under `tests/Fixtures/V2/ReplayRegression/`. Each fixture names an autoloadable workflow and is executed through the production `WorkflowFiberRunner` using either persisted history or a worker command sequence. +3. Shared codec evidence belongs under `tests/Fixtures/V2/CodecRegression/` and in every applicable official binding. +4. Fixtures must preserve protocol version, value and type, framing, and stable failure policy. +5. Existing evidence is **append-only**. Do not modify existing evidence unless explicitly directed by maintainers. + +To validate your regression corpus additions against a target branch, run the validation script: + +```bash +python scripts/ci/validate-regression-corpus.py --base-ref main +``` + +## Pull Request Process + +1. Follow the Pull Request template provided when opening a PR. +2. Update the README.md or docs if your changes impact user-facing APIs. +3. The CI pipelines will automatically run on your PR. You must have all CI checks (ECS, PHPStan, PHPUnit) passing before your PR can be merged.