From dd6d117d4939c743c0da522b470a0301f3dff748 Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Thu, 6 Aug 2026 09:24:53 +0300 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=BF=D1=80=D0=B0=D0=B2=D0=BA?= =?UTF-8?q?=D0=B0=20=D1=82=D0=B5=D0=BB=D0=B0=20issue=20=D0=B8=D0=B4=D1=91?= =?UTF-8?q?=D1=82=20=D1=87=D0=B5=D1=80=D0=B5=D0=B7=20API,=20=D0=B0=20?= =?UTF-8?q?=D0=BD=D0=B5=20=D1=87=D0=B5=D1=80=D0=B5=D0=B7=20tea?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Зачем: тикнуть чекбокс в критериях приёмки нужно при закрытии каждой задачи, а рецепта в доке не было. Наступили на это при закрытии #37: `tea issues edit --description` требует тело целиком строкой, но взять её неоткуда — вывод `tea issues <номер>` обёрнут и разрисован для терминала. Что: раздел «Правка тела issue — только через API» с рабочим рецептом (забрать сырой JSON, поправить body, вернуть через `-X PATCH -d @файл`) и разбором флагов `tea api`. Оттуда же общее правило: CLI удобен, пока команда создаёт объект или меняет его свойство, и мешает, как только надо изменить уже написанный текст. Ссылка из раздела про автозакрытие и запись в «Что проверено и когда». Проверка: рецепт снят живыми запросами при закрытии #37 — так проставлены чекбоксы тикета и пункт в чек-листе карты #4. `make config-test` зелёный. Co-Authored-By: Claude Opus 5 --- docs/agents/issue-tracker.md | 47 +++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 427e206..38b4469 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -46,6 +46,45 @@ уже с сохранённым токеном, например `tea api repos/ddmitry/clickstream-data-platform/issues/18`. +## Правка тела issue — только через API + +Тикнуть чекбокс в критериях приёмки нужно при закрытии каждой задачи, и `tea` +для этого не годится. `tea issues edit --description` принимает тело **целиком +строкой**, а взять эту строку неоткуда: `tea issues <номер>` печатает текст +обёрнутым и разрисованным для терминала, обратно его не скормишь. + +Рабочий путь — забрать сырое тело из API, поправить и вернуть: + +```sh +# 1. сырой JSON тикета; тело — в поле body +tea api repos/{owner}/{repo}/issues/ > issue.json + +# 2. правка тела любым удобным способом, например все чекбоксы разом +python3 -c " +import json +d = json.load(open('issue.json')) +json.dump({'body': d['body'].replace('- [ ]', '- [x]')}, + open('patch.json', 'w'), ensure_ascii=False) +" + +# 3. вернуть +tea api -X PATCH -d @patch.json repos/{owner}/{repo}/issues/ +``` + +Флаги `tea api`: `-X` — метод, `-d` — сырое тело JSON (`@файл` читает из файла, +`@-` из потока ввода), `-f` и `-F` — отдельные поля строкой и с типом. Флага +`--input` нет, хотя рука тянется написать именно его. + +Тот же приём — для чек-листа родительской карты: пункт `- [ ] #NN` тикается +правкой её тела, автоматически Gitea этого не делает. + +**Отсюда общее правило.** `tea` удобен там, где команда создаёт объект или +меняет его свойство: создать issue, добавить комментарий, повесить метку, +назначить исполнителя, закрыть. Как только нужно **изменить уже написанный +текст** — тело issue, тело PR, — CLI мешает: он умеет только заменить всё +целиком, а прочитать это «всё» в пригодном для правки виде не даёт. Такие +операции идут прямо в API. + ## Слияние PR не закрывает issue Gitea понимает только английские ключевые слова автозакрытия: `closes`, @@ -59,7 +98,8 @@ PR #17, где issue #13 пришлось закрывать руками. Если ключевого слова не было, порядок после слияния: закрыть задачу (`tea issues close <номер>`) и тикнуть её пункт в чек-листе родительского -issue этапа — Gitea чек-листы сама не обновляет. +issue этапа — Gitea чек-листы сама не обновляет. Чем тикать — выше, в разделе +про правку тела. ## Спека — источник истины @@ -119,6 +159,11 @@ issue этапа — Gitea чек-листы сама не обновляет. ## Что проверено и когда +2026-08-06: правка тела issue через `tea api -X PATCH -d @файл` снята живыми +запросами при закрытии #37 — так проставлены чекбоксы самого тикета и пункт +в чек-листе карты #4. Тогда же проверено, что `tea issues edit --description` +для этого непригоден, а флага `--input` у `tea api` нет. + 2026-07-31: Gitea 1.27.0 (`tea api version`), `tea` 0.15.0. Живыми запросами по этому репозиторию проверены `tea labels list` и `tea issues list`. Остальной набор команд, флагов и приёмы с `tea api` перенесены из доки