Додавання прикладу

Sample App — це канонічне місце для демонстрації шаблонів Durable Workflow у справжньому Laravel-проєкті. Якщо ваш шаблон може допомогти іншим інженерам, наприклад нова структура saga, інше використання потоків повідомлень або інтеграція з інструментом, якого ще немає в прикладах, цей посібник допоможе включити його до проєкту.

Цей контракт навмисно короткий. Приклад, який його дотримується, потрапляє до проєкту в передбачуваний строк. Приклад із пропущеними вимогами залишається на розгляді, доки прогалини не буде заповнено.

Перед написанням коду

1. Спочатку відкрийте issue sample-request. Шаблон sample-request визначає можливість, публічну сторінку документації з її контрактом і мінімальну потрібну версію пакета Durable Workflow. В issue супроводжувачі й автор погоджують цінність прикладу до роботи над PR.
2. Оберіть можливість, якої ще немає в індексі прикладів. Індекс прикладів README перелічує всі показані шаблони. Якщо ідея зводиться до іншого запису простого workflow, це зміна документації App\Workflows\Simple\SimpleWorkflow, а не новий приклад.
3. Знайдіть найближчий наявний клас workflow. Новий приклад має бути схожим на сусідні: та сама структура каталогів app/Workflows/<Pattern>/, форма команди Artisan і підхід до тестів. Приклади з новою довільною інфраструктурою відхиляються, навіть якщо показаний шаблон корисний.

Яким має бути прийнятий приклад

Прийнятий приклад є виконуваним, зрозумілим для навчання, перевіреним тестами й доступним для пошуку. Для цього в репозиторії sample-app мають бути чотири конкретні складові:

1. Клас workflow у app/Workflows/<Pattern>/, який демонструє шаблон від початку до кінця. Код workflow залишається детермінованим: читання часу через sideEffect(), зовнішня робота в activity, очікування через signal, update, timer або потоки повідомлень. Клас компілюється без OPENAI_API_KEY та інших зовнішніх облікових даних, якщо шаблон не вимагає їх явно.
2. Команда Artisan, яка запускає workflow з реалістичними вхідними даними, щоб читач виконав одну команду й побачив запуск у Waterline. Вона розміщується поруч із відповідними командами Artisan у routes/console.php або аналогічному місці реєстрації та дотримується тієї самої схеми назв app:<short-pattern>.
3. Запис config/workflow_mcp.php із класом workflow, шаблоном, командою, потрібними обліковими даними й аргументами. Він робить приклад доступним через MCP-сервер. Перевірка upstream-coverage не позначає рядок покриття як covered, доки запис не з’явиться.
4. Тест у tests/, який виконує workflow через worker v2 у пам’яті. Не потрібно перевіряти кожну типізовану подію історії, але тест має довести завершення workflow для вхідних даних команди Artisan.

Якщо приклад демонструє виправлення помилки, а не можливість, він розміщується в app/Workflows/Bug/<short-id>/ із тими самими чотирма складовими.

Зміни документації

Після прийняття прикладу оновлюються три частини документації:

• Sample Index у README репозиторію sample-app — один рядок для кожного прикладу з метою, класом workflow, командою Artisan і ключем MCP. Це джерело істини.
• Галерея прикладів на сайті документації (docs/sample-app.md) — відображення того самого рядка з очікуваним екраном Waterline. Галерея дає читачу змогу обрати відповідний приклад перед клонуванням репозиторію.
• Посилання зі сторінки шаблону документації, що визначає можливість: saga, signal, потоки повідомлень, дочірні workflow тощо. Таблиця посилань унизу сторінки sample-app є канонічним списком. Запис із назвою можливості без посилання на приклад вважається прогалиною.

Надсилайте приклад і зміни README у PR sample-app, а галерею та зміни сторінки шаблону — у пов’язаному PR сайту документації. Супроводжувачі включають пов’язані зміни разом. Приклад без відображення на сайті документації має стан gap у трекері upstream-coverage до прийняття PR документації, тому авторам рекомендується готувати їх разом.

Назви, структура й стиль

• Структура класів. app/Workflows/<Pattern>/<Pattern>Workflow.php із класами activity поруч у app/Workflows/<Pattern>/Activities/. Відтворення помилок розміщуються в app/Workflows/Bug/<short-id>/ за тією самою структурою.
• Команда Artisan. app:<short-pattern> малими літерами без дефісів. Довгі назви на кшталт app:run-<pattern> не використовуються.
• Ключ MCP. Має відповідати короткій назві шаблону команди Artisan, щоб MCP-клієнт бачив ту саму назву, яку людина вводить у терміналі.
• Коментарі. Пояснюйте чому, а не що. Інваріанти безпеки replay варто коментувати: чому значення обгорнуте в sideEffect() або чому очікування використовує timer замість usleep(). Однаковий коментар біля кожного виклику activity не потрібен.
• Знімки екрана Waterline. Галерея sample-app на сайті документації визначає очікуваний екран Waterline. Додайте або оновіть його в межах роботи над прикладом.

Причини відхилення прикладу

Приклад повертається на доопрацювання, якщо:

• код workflow використовує now(), random_*() або інші недетерміновані виклики поза sideEffect() або activity;
• activity виконують стійкий облік, яким уже керує рушій: прямо записують workflow_messages, вручну переміщують курсори потоків або зберігають стан Waterline з коду workflow;
• команда Artisan вимагає зовнішніх облікових даних без зазначення цього в полі requires запису MCP;
• індекс прикладів README, рядок галереї документації та посилання зі сторінки шаблону не входять до однієї узгодженої зміни;
• приклад повторює наявну можливість без нової структури, сценарію помилки або інтеграції. Той самий шаблон з іншим описом є зміною документації, а не новим прикладом.

Ці самі вимоги перевіряють upstream-coverage та список перевірки sample-app. Виправлення прогалин перед відкриттям PR пришвидшує його прийняття.

Короткий список перевірки

Використовуйте цей список під час відкриття PR:

• Є issue sample-request із посиланням на публічну сторінку шаблону.
• Клас workflow у app/Workflows/<Pattern>/.
• Команда Artisan зареєстрована з назвою app:<short-pattern>.
• Запис config/workflow_mcp.php із класом, шаблоном, командою, вимогами й аргументами.
• Тест, який виконує workflow від початку до кінця.
• Рядок Sample Index у README.
• Рядок галереї сайту документації у docs/sample-app.md.
• Посилання з відповідної сторінки шаблону на сайті документації.
• Перевірка публічних меж пройшла (scripts/check-public-boundary.sh).

Супроводжувачі перевіряють той самий список, тому PR, який виконує всі вимоги, має потрапити до проєкту протягом одного циклу випуску.