From 6c9d98611467bcb4cb7a649161ca6cb8bfeee435 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Wed, 29 Jul 2026 21:25:05 +0300 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=BA=D0=BE=D0=BD=D1=82=D1=80?= =?UTF-8?q?=D0=B0=D0=BA=D1=82=20=D1=82=D1=80=D0=B5=D0=BA=D0=B5=D1=80=D0=B0?= =?UTF-8?q?=20=D0=BF=D0=B5=D1=80=D0=B5=D0=B2=D0=B5=D0=B4=D1=91=D0=BD=20?= =?UTF-8?q?=D0=BD=D0=B0=20Gitea=20=D0=B8=20CLI=20tea?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - GitHub-аккаунт заблокирован, работа идёт в Gitea на git.dementev.space, а инструкции для агентов всё ещё описывали GitHub Issues и gh. - Что: - docs/agents/issue-tracker.md переписан под Gitea и tea 0.15.0: установка, вход, скоупы токена, обход прокси, команды для issues/комментариев/меток; - блокировки переведены на нативные зависимости Gitea через tea api, текстовые строки Blocked by из тел тикетов убраны; - GitHub ушёл одной строкой в раздел «Архив»; - docs/agents/triage-labels.md и блок «Agent skills» в AGENTS.md переобвязаны на Gitea. - Проверка: - tea issues list, tea labels list — читают трекер; - граф блокировок карты #10 собран заново и прочитан обратно через tea api repos/{owner}/{repo}/issues//dependencies. --- AGENTS.md | 4 +- docs/agents/issue-tracker.md | 124 ++++++++++++++++++++++++++--------- docs/agents/triage-labels.md | 7 +- 3 files changed, 99 insertions(+), 36 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1565fa6..5e33405 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,11 +41,11 @@ ### Issue tracker -GitHub Issues (через CLI `gh`). Спека фичи — файлом в `docs/specs/` (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. `docs/agents/issue-tracker.md`. +Gitea на `git.dementev.space` (через CLI `tea`). Спека фичи — файлом в `docs/specs/` (источник истины), корневой issue — тонкий, со ссылкой на спеку и чек-листом дочерних issues. См. `docs/agents/issue-tracker.md`. ### Triage labels -Пять канонических ролей как метки GitHub, имена совпадают (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`. +Пять канонических ролей как метки Gitea, имена совпадают (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). См. `docs/agents/triage-labels.md`. ### Domain docs diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index aeb9959..3a6d614 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -1,16 +1,52 @@ -# Issue tracker: GitHub +# Issue tracker: Gitea -Задачи этого репозитория живут в GitHub Issues. Все операции — через CLI `gh`; -репозиторий `gh` определяет сам по `git remote`. +Задачи этого репозитория живут в Gitea на `git.dementev.space` +(`ddmitry/clickstream-ch-kafka-superset-demo`, это remote `origin`). Все +операции — через CLI [`tea`](https://gitea.com/gitea/tea), официальный клиент +Gitea; по устройству он близок к `gh` и `glab`. Логин и репозиторий `tea` +определяет сам по git remote в текущем каталоге. -- **Создать issue**: `gh issue create --title "..." --body "..."` (многострочное - тело — heredoc'ом). -- **Прочитать issue**: `gh issue view <номер> --comments`. -- **Список**: `gh issue list --state open --json number,title,labels` с нужными - фильтрами `--label` / `--state`. -- **Комментарий**: `gh issue comment <номер> --body "..."`. -- **Метки**: `gh issue edit <номер> --add-label "..."` / `--remove-label "..."`. -- **Закрыть**: `gh issue close <номер> --comment "..."`. +## Перед первым запуском + +- **Бинарник.** Скачивается с `https://dl.gitea.com/tea/<версия>/` (файл + `tea-<версия>-linux-amd64` и `.sha256` рядом), кладётся в `~/.local/bin/tea`. + Проверка: `tea --version`. +- **Вход.** `tea logins add --name git.dementev.space --url + https://git.dementev.space`, токен передаётся переменной + `GITEA_SERVER_TOKEN` (не аргументом командной строки — он попадёт в историю + оболочки). Логин уже добавлен и назначен по умолчанию, так что `tea` работает + из любого каталога. +- **Скоупы токена:** `read:user` (без него `tea` откажется добавлять логин), + `write:issue`, `write:repository`. Токен выпускается в UI: Settings → + Applications. Нехватка скоупа выглядит не как «нет прав», а как невнятная + ошибка или пустой ответ — на этом уже один раз потеряли нативные блокировки + (решили, что их нет в установке). +- **Прокси.** Домен `dementev.space` должен быть в `NO_PROXY`, иначе запросы + уходят в прокси и виснут. В обычной оболочке это делает `proxy-client` из + `~/dotfiles`; для агента в t3 — блок `environment` в + `~/.t3/userdata/settings.json`. Если переменная не подхватилась, короткий + разовый префикс: `NO_PROXY='*' tea ...`. + +## Команды + +- **Создать issue:** `tea issues create --title "..." --description "..."`. + Многострочное тело удобнее собрать heredoc'ом в переменную и подставить + как `--description "$BODY"`. +- **Прочитать issue:** `tea issues <номер> --comments`. +- **Список:** `tea issues list --state open --output json --fields + index,title,labels,assignees`. Фильтры: `--labels`, `--assignee`, + `--keyword`. +- **Комментарий:** `tea comments add <номер> -d "..."`. +- **Метки:** `tea issues edit <номер> --add-labels "..."` / `--remove-labels + "..."`. Список меток репозитория — `tea labels list`, создать новую — + `tea labels create --name "..." --color "..."`. +- **Закрыть:** `tea issues close <номер>`. Комментария при закрытии команда не + принимает — сначала `tea comments add`, потом `close`. +- **Взять в работу:** `tea issues edit <номер> --add-assignees ddmitry`. + Сокращения вида `@me` в `tea` нет, имя пишется целиком. +- **Чего нет в CLI** — через `tea api `: команда ходит в REST API Gitea + уже с сохранённым токеном, например + `tea api repos/ddmitry/clickstream-ch-kafka-superset-demo/issues/17`. ## Спека — источник истины @@ -25,39 +61,65 @@ ## Когда скилл говорит «опубликовать в issue tracker» -Создать GitHub issue. +Создать issue в Gitea: `tea issues create ...`. ## Когда скилл говорит «достать тикет» -`gh issue view <номер> --comments`. +`tea issues <номер> --comments`. ## PR как поверхность триажа **Нет** — одиночный учебный репозиторий, внешних PR не ждём. (Если включить — -`/triage` начнёт гонять PR через те же метки и состояния командами `gh pr ...`.) +`/triage` начнёт гонять PR через те же метки и состояния командами +`tea pulls ...`.) ## Wayfinding-операции Используются `/wayfinder`. Карта — один issue, тикеты — дочерние issues. -- **Карта**: issue с меткой `wayfinder:map` (Notes / Decisions-so-far / Fog в теле). -- **Дочерний тикет**: sub-issue карты (`gh api` на endpoint sub-issues); если - sub-issues недоступны — пункт task-list в теле карты + `Part of #` в - начале тела тикета. Метки: `wayfinder:` (`research`/`prototype`/ - `grilling`/`task`). -- **Блокировки**: нативные issue dependencies — - `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=` - (`` — числовой database id: `gh api repos///issues/ --jq .id`, - не `#номер`). Fallback — строка `Blocked by: #` в начале тела. Тикет - разблокирован, когда все блокеры закрыты. +- **Карта**: issue с меткой `wayfinder:map` (Notes / Decisions-so-far / Fog + в теле). +- **Дочерний тикет**: вложенных issues в Gitea нет, поэтому связь держится + двумя ссылками — пункт списка `- [ ] #NN` в теле карты и строка + `Part of #<карта>` в начале тела тикета. Метки: `wayfinder:<тип>` + (`research` / `prototype` / `grilling` / `task`). +- **Блокировки**: нативные зависимости Gitea — единственный источник истины, + текстовых строк `Blocked by:` в телах тикетов больше нет. В CLI их команд + нет, работаем через `tea api` (`{owner}` и `{repo}` подставляются из текущего + репозитория): + - добавить блокер: `tea api repos/{owner}/{repo}/issues//dependencies + -F index=<блокер> -f owner=ddmitry -f repo=clickstream-ch-kafka-superset-demo` + — поля `owner` и `repo` обязательны, без них API отвечает + «repository does not exist»; + - кто блокирует тикет: `GET .../issues//dependencies`; + - кого блокирует тикет: `GET .../issues//blocks`; + - снять блокировку: тот же путь методом `DELETE` с тем же телом. + + Тикет разблокирован, когда у всех блокеров `state == "closed"`. - **Фронтир**: открытые дети карты минус заблокированные и назначенные; первый - в порядке карты. -- **Взять в работу**: `gh issue edit --add-assignee @me`. -- **Закрыть**: комментарий с ответом, `gh issue close`, указатель на контекст — - в Decisions-so-far карты. + в порядке карты. Блокеры проверяются запросом `dependencies` по каждому + кандидату. +- **Взять в работу**: `tea issues edit --add-assignees ddmitry` — первая + запись за сессию. +- **Закрыть**: `tea comments add -d "<ответ>"`, затем `tea issues close + `, затем указатель на контекст (суть + ссылка) в Decisions-so-far карты. + +## Что проверено и когда + +2026-07-29: Gitea 1.27.0, `tea` 0.15.0. Список команд и флагов снят с +`tea <команда> --help` установленного бинарника, а не из документации в вебе. +При обновлении `tea` стоит перечитать `--help`: набор флагов между версиями +менялся. Нативные зависимости и правка тел тикетов через `tea api` проверены +живыми запросами: граф блокировок карты #10 в тот день собран заново +(#17 ← #14, #15, #16; #14 ← #12, #13, #18; #16 ← #15). ## Архив -До 2026-07-19 задачи велись markdown-файлами в `.scratch//issues/` -(фичи `data-generator` и `generator-model-time-startup-history`, задачи 01–21). -Не мигрированы; доступны в истории git — срез `0e312b3`. +- До 2026-07-26 трекер жил в GitHub Issues (`dementev-dev/…`). Аккаунт + заблокирован, remote `github` заморожен; все 27 номеров issues воссозданы в + Gitea один в один. Слепок трекера на момент блокировки — + `.scratch/backup/20260726-tracker-snapshot.md` (ветка + `chore/gitea-migration`). +- До 2026-07-19 задачи велись markdown-файлами в `.scratch//issues/` + (фичи `data-generator` и `generator-model-time-startup-history`, задачи + 01–21). Не мигрированы; доступны в истории git — срез `0e312b3`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index a1a76a8..a0b0a3b 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -1,9 +1,9 @@ # Triage labels Скиллы оперируют пятью каноническими ролями триажа. Здесь они сопоставлены с -метками GitHub Issues этого репозитория. +метками issues этого репозитория в Gitea. -| Роль в mattpocock/skills | Метка GitHub | Значение | +| Роль в mattpocock/skills | Метка Gitea | Значение | | ------------------------ | ----------------- | ---------------------------------------------- | | `needs-triage` | `needs-triage` | Мейнтейнеру нужно оценить задачу | | `needs-info` | `needs-info` | Ждём от репортёра дополнительную информацию | @@ -12,4 +12,5 @@ | `wontfix` | `wontfix` | Не будет сделано | Правый столбец можно поменять под свою лексику. Сейчас — дефолт (метка = имя -роли); метки созданы в репозитории GitHub. +роли); все пять меток заведены в репозитории Gitea. Посмотреть текущий список — +`tea labels list`.