From 6e52c53906b0f3d783af2216b3473b8839a2e0d4 Mon Sep 17 00:00:00 2001 From: Aleksey Sabilin Date: Tue, 7 Jul 2026 16:53:59 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20WSL=20=D0=B8?= =?UTF-8?q?=20git-=D0=BA=D0=BE=D0=BC=D0=BC=D0=B8=D1=82=D1=8B=20=D1=87?= =?UTF-8?q?=D0=B5=D1=80=D0=B5=D0=B7=20=D1=82=D0=B5=D1=80=D0=BC=D0=B8=D0=BD?= =?UTF-8?q?=D0=B0=D0=BB=20WSL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- WORKFLOW.md | 245 +++++++++++++++++++++++++++++----------------------- 1 file changed, 137 insertions(+), 108 deletions(-) diff --git a/WORKFLOW.md b/WORKFLOW.md index f987596..af88316 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -1,108 +1,137 @@ -# EventHub — правила работы - -Живой документ процесса разработки. Дополняется по мере появления новых договорённостей. - -**Репозитории:** `EventHubBack`, `EventHubFrontAdmin`, `EventHubSpec` -**Трекер:** https://git.sabilin.com/EventHub -**Cursor skill для задач:** `eventhub-gitea` - ---- - -## 1. Задачи (Gitea) - -### Язык -Все задачи, комментарии и описания — **на русском**. -Исключение: имена файлов, пути API, идентификаторы в backticks. - -### Жизненный цикл - -| Этап | Действие | -|------|----------| -| Старт | Прочитать issue → назначить на себя → комментарий «Беру в работу» | -| План | **Предложить 1–3 варианта решения с trade-offs → ждать утверждения** | -| Работа | После утверждения — код в репозитории-владельце; коммиты с `Refs EventHub/#N` | -| Финиш | Тесты зелёные → комментарий с итогом → закрыть issue | - -### Метки (единый набор во всех репо) - -| Метка | Назначение | -|-------|------------| -| Bug | Дефект | -| Task | Техническая задача | -| Story | Пользовательская история | -| Epic | Крупная инициатива | -| Future | Отложено | - -Синхронизация меток: `~/.cursor/skills/eventhub-gitea/scripts/sync-labels.ps1` - -### Приоритеты -`P0` → `P1` → `P2` (указывается в заголовке задачи). - ---- - -## 2. Тестирование (обязательный gate) - -**Нельзя** закрывать задачу и **нельзя** обновлять спеку, пока: - -- пройдены релевантные тесты репозитория; -- выполнена ручная проверка, если автотестов нет; -- нет известных регрессий в затронутой области. - -| Репозиторий | Минимум | -|-------------|---------| -| EventHubBack | `make test` / `make eunit` / целевые API-тесты | -| EventHubFrontAdmin | `npm run lint`, `npm run build` | -| EventHubSpec | ревью текста, ссылки на код | - ---- - -## 3. Спецификация (после успешных тестов) - -Если изменение затрагивает **поведение, API, модель данных или роли**: - -1. Обновить соответствующий файл в `EventHubSpec/`: - - backend → `EventHubBackSpec.md` - - admin → `EventHubFrontAdminSpec.md` -2. В комментарии к issue указать: «Спека обновлена: …» -3. Спека описывает **фактическую** реализацию, не планы. - -Что синхронизировать: -- endpoint-ы (путь, метод, auth); -- форматы запросов/ответов; -- поля records/таблиц; -- роли и права; -- ограничения и допущения. - -Чистый рефакторинг без смены контракта — обновление спеки не обязательно (написать в issue). - ---- - -## 4. Расширение правил - -При появлении новой договорённости в работе: - -1. Добавить пункт в этот файл (раздел «Правила» ниже). -2. При необходимости — задача `Task` в `EventHubSpec` на согласование. -3. Для Cursor — обновить skill `eventhub-workflow`. - ---- - -## Правила (накопительный список) - -- Задачи в Gitea вести через skill `eventhub-gitea`; тексты на русском. -- **Перед реализацией** — предложить оптимальные варианты решения; кодить только после утверждения варианта пользователем. -- Перед закрытием issue — успешные тесты изменённого кода. -- После успешных тестов — обновить спеку, если менялся внешний контракт. -- Одна задача — один логический объём работы. -- Код фичи — в репозитории-владельце; `EventHubSpec` — для документации и процесса. -- Метки во всех репозиториях держать одинаковыми (`sync-labels.ps1`). -- Секреты и токены не коммитить; Gitea token — только в env / `~/.cursor/secrets/`. - ---- - -## История - -| Дата | Изменение | -|------|-----------| -| 2026-07-07 | Правило: варианты решения и утверждение перед реализацией | -| 2026-07-07 | Первая версия: Gitea workflow, gate тестирования, sync спеки | +# EventHub — правила работы + +Живой документ процесса разработки. Дополняется по мере появления новых договорённостей. + +**Репозитории:** `EventHubBack`, `EventHubFrontAdmin`, `EventHubSpec` +**Трекер:** https://git.sabilin.com/EventHub +**Cursor skill для задач:** `eventhub-gitea` + +--- + +## 1. Задачи (Gitea) + +### Язык +Все задачи, комментарии и описания — **на русском**. +Исключение: имена файлов, пути API, идентификаторы в backticks. + +### Жизненный цикл + +| Этап | Действие | +|------|----------| +| Старт | Прочитать issue → назначить на себя → комментарий «Беру в работу» | +| План | **Предложить 1–3 варианта решения с trade-offs → ждать утверждения** | +| Работа | После утверждения — код в репозитории-владельце; коммиты с `Refs EventHub/#N` | +| Финиш | Тесты зелёные → комментарий с итогом → закрыть issue | + +### Метки (единый набор во всех репо) + +| Метка | Назначение | +|-------|------------| +| Bug | Дефект | +| Task | Техническая задача | +| Story | Пользовательская история | +| Epic | Крупная инициатива | +| Future | Отложено | + +Синхронизация меток: `~/.cursor/skills/eventhub-gitea/scripts/sync-labels.ps1` + +### Приоритеты +`P0` → `P1` → `P2` (указывается в заголовке задачи). + +--- + +## 2. Тестирование (обязательный gate) + +**Нельзя** закрывать задачу и **нельзя** обновлять спеку, пока: + +- пройдены релевантные тесты репозитория; +- выполнена ручная проверка, если автотестов нет; +- нет известных регрессий в затронутой области. + +| Репозиторий | Минимум | +|-------------|---------| +| EventHubBack | `make test` / `make eunit` / целевые API-тесты (см. §2.1 WSL) | +| EventHubFrontAdmin | `npm run lint`, `npm run build` | +| EventHubSpec | ревью текста, ссылки на код | + +--- + +## 2.1. Локальная разработка (WSL) + +Окружение: **WSL + asdf** (Erlang/OTP 28, rebar3). PowerShell/Windows — только IDE; сборка и тесты — в WSL. + +```bash +cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack +bash scripts/wsl-ext4-dirs.sh # один раз: logs/data на ext4 +bash scripts/fix-rebar-unit-symlink.sh # перед CT, если rebar сломал unit/api +rebar3 as test eunit +rebar3 ct --suite=api_admins_SUITE +``` + +### Git-коммиты — только из WSL-терминала + +Коммиты из **Agent Shell / PowerShell** ломаются: Cursor подставляет `--trailer "Co-authored-by: Cursor "`, а PowerShell падает на `<`. + +**Правило:** `git add` / `git commit` / `git push` — в WSL (`bash -lic` или встроенный терминал WSL), не через Agent. + +```bash +cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack # или EventHubSpec +git status +git add +git commit -m "сообщение. Refs EventHub/EventHubBack#N" +``` + +Attribution в Cursor (Settings → Agent → Attribution) можно выключить, но WSL-терминал надёжнее. + +--- + +Если изменение затрагивает **поведение, API, модель данных или роли**: + +1. Обновить соответствующий файл в `EventHubSpec/`: + - backend → `EventHubBackSpec.md` + - admin → `EventHubFrontAdminSpec.md` +2. В комментарии к issue указать: «Спека обновлена: …» +3. Спека описывает **фактическую** реализацию, не планы. + +Что синхронизировать: +- endpoint-ы (путь, метод, auth); +- форматы запросов/ответов; +- поля records/таблиц; +- роли и права; +- ограничения и допущения. + +Чистый рефакторинг без смены контракта — обновление спеки не обязательно (написать в issue). + +--- + +## 4. Расширение правил + +При появлении новой договорённости в работе: + +1. Добавить пункт в этот файл (раздел «Правила» ниже). +2. При необходимости — задача `Task` в `EventHubSpec` на согласование. +3. Для Cursor — обновить skill `eventhub-workflow`. + +--- + +## Правила (накопительный список) + +- Задачи в Gitea вести через skill `eventhub-gitea`; тексты на русском. +- **Перед реализацией** — предложить оптимальные варианты решения; кодить только после утверждения варианта пользователем. +- Перед закрытием issue — успешные тесты изменённого кода. +- После успешных тестов — обновить спеку, если менялся внешний контракт. +- Одна задача — один логический объём работы. +- Код фичи — в репозитории-владельце; `EventHubSpec` — для документации и процесса. +- Метки во всех репозиториях держать одинаковыми (`sync-labels.ps1`). +- Секреты и токены не коммитить; Gitea token — только в env / `~/.cursor/secrets/`. +- **Git commit/push — из WSL-терминала**, не из Agent Shell (см. §2.1). + +--- + +## История + +| Дата | Изменение | +|------|-----------| +| 2026-07-07 | §2.1: WSL-окружение, git-коммиты только из WSL-терминала | +| 2026-07-07 | Правило: варианты решения и утверждение перед реализацией | +| 2026-07-07 | Первая версия: Gitea workflow, gate тестирования, sync спеки |