Документировать WSL и git-коммиты через терминал WSL
This commit is contained in:
+137
-108
@@ -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/<repo>#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/<repo>#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 <cursoragent@cursor.com>"`, а 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 <files>
|
||||
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 спеки |
|
||||
|
||||
Reference in New Issue
Block a user