@rt-tools/agent-kit 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/checks/check-file-size.mjs +19 -4
- package/assets/checks/check-state-next.mjs +202 -0
- package/assets/checks/check-states.mjs +142 -0
- package/assets/checks/check-turn-map.mjs +146 -0
- package/assets/checks/rt-kit-checks.config.mjs +16 -2
- package/assets/defaults/project.sh +67 -7
- package/assets/defaults/turn-map.md +48 -0
- package/assets/hooks/browser-device-id.sh +2 -0
- package/assets/hooks/browser-guard-device-id.sh +5 -1
- package/assets/hooks/browser-guard-no-asking.sh +5 -1
- package/assets/hooks/browser-guard-no-listing.sh +2 -0
- package/assets/hooks/browser-guard-no-other-drivers.sh +7 -3
- package/assets/hooks/browser-guard-require-select.sh +6 -2
- package/assets/hooks/claim-guard.sh +5 -1
- package/assets/hooks/commit-msg.sh +2 -0
- package/assets/hooks/conscience-guard.sh +5 -1
- package/assets/hooks/constitution-index.sh +2 -0
- package/assets/hooks/dev-server-guard.sh +7 -3
- package/assets/hooks/dispatch.sh +69 -0
- package/assets/hooks/docs-guard.sh +8 -4
- package/assets/hooks/exam-guard.sh +7 -3
- package/assets/hooks/git-guard-delivery-signature.sh +2 -0
- package/assets/hooks/git-guard-delivery.sh +39 -5
- package/assets/hooks/git-guard-main.sh +8 -4
- package/assets/hooks/git-guard-push-tests.sh +8 -4
- package/assets/hooks/glossary-load.sh +2 -0
- package/assets/hooks/grill-gate.sh +6 -2
- package/assets/hooks/handoff-entry-guard.sh +6 -2
- package/assets/hooks/handoff-write.sh +124 -0
- package/assets/hooks/hook-input.sh +54 -0
- package/assets/hooks/lint-after-edit.sh +7 -3
- package/assets/hooks/observe.sh +2 -0
- package/assets/hooks/postmortem-guard.sh +5 -1
- package/assets/hooks/proposal-guard.sh +5 -1
- package/assets/hooks/prose-style-guard.sh +7 -3
- package/assets/hooks/qa-dataid-guard.sh +6 -2
- package/assets/hooks/rerun-guard.sh +7 -3
- package/assets/hooks/reuse-first-guard.sh +7 -3
- package/assets/hooks/roles.sh +2 -0
- package/assets/hooks/rule-article.sh +99 -0
- package/assets/hooks/skill-gate-layers.sh +2 -0
- package/assets/hooks/skill-gate-rearm.sh +5 -1
- package/assets/hooks/skill-gate.sh +25 -2
- package/assets/hooks/skill-loaded.sh +5 -1
- package/assets/hooks/sql-guard-parse.sh +2 -0
- package/assets/hooks/sql-guard-request.sh +4 -1
- package/assets/hooks/sql-guard-target.sh +2 -0
- package/assets/hooks/sql-guard-write.sh +2 -0
- package/assets/hooks/sql-guard.sh +6 -2
- package/assets/hooks/task-context-load.sh +2 -0
- package/assets/hooks/task-flow-guard.sh +8 -4
- package/assets/hooks/turn-entry-load.sh +62 -0
- package/assets/hooks/turn-exit-guard.sh +44 -17
- package/assets/hooks/utf8.sh +35 -0
- package/assets/hooks/waiting-turn-guard.sh +5 -1
- package/assets/hooks/window-fill-guard.sh +37 -5
- package/assets/laws/work-conduct.md +34 -9
- package/assets/patterns/dependencies-upgrade.md +1 -1
- package/assets/patterns/doc-style-write.md +3 -3
- package/assets/patterns/git-workflow-commit.azure.md +2 -202
- package/assets/patterns/git-workflow-commit.github.md +2 -258
- package/assets/patterns/git-workflow-commit.gitlab.md +1 -217
- package/assets/patterns/git-workflow-docker.md +3 -3
- package/assets/patterns/git-workflow-merge.md +3 -2
- package/assets/patterns/git-workflow-migration.md +3 -3
- package/assets/patterns/git-workflow-pr.azure.md +224 -0
- package/assets/patterns/git-workflow-pr.github.md +280 -0
- package/assets/patterns/git-workflow-pr.gitlab.md +240 -0
- package/assets/patterns/git-workflow-restart.md +3 -3
- package/assets/patterns/git-workflow-secrets.md +3 -3
- package/assets/patterns/task-flow-archive.md +193 -0
- package/assets/patterns/task-flow-close.md +11 -160
- package/assets/patterns/task-flow-handoff.md +22 -4
- package/assets/patterns/task-flow-resume.md +6 -0
- package/assets/patterns/task-flow-start.md +41 -0
- package/assets/patterns/turn-entry-map.md +81 -0
- package/assets/pitfalls/doc-style.md +80 -0
- package/assets/pitfalls/git-workflow.azure.md +50 -0
- package/assets/pitfalls/git-workflow.github.md +78 -0
- package/assets/pitfalls/git-workflow.gitlab.md +49 -0
- package/assets/pitfalls/spec-driven.md +36 -0
- package/assets/pitfalls/styling-bem.md +45 -0
- package/assets/pitfalls/task-flow.md +62 -0
- package/assets/pitfalls/testing.md +70 -0
- package/assets/rules/deploy-flow.azure.md +106 -0
- package/assets/rules/deploy-flow.github.md +113 -0
- package/assets/rules/deploy-flow.gitlab.md +108 -0
- package/assets/rules/doc-style.md +25 -76
- package/assets/rules/git-workflow.azure.md +6 -92
- package/assets/rules/git-workflow.github.md +14 -127
- package/assets/rules/git-workflow.gitlab.md +6 -93
- package/assets/rules/spec-driven.md +39 -30
- package/assets/rules/styling-bem.md +20 -39
- package/assets/rules/task-flow.md +17 -186
- package/assets/rules/testing.md +3 -64
- package/assets/rules/turn-conduct.md +206 -0
- package/assets/rules/turn-entry.md +93 -0
- package/assets/rules/typescript-conventions.md +15 -0
- package/assets/skills/agent-kit.md +35 -12
- package/assets/templates/pitfalls.md +10 -0
- package/assets/templates/rule.md +5 -3
- package/lib/assets.d.ts.map +1 -1
- package/lib/assets.js +6 -1
- package/lib/assets.js.map +1 -1
- package/lib/cargo.d.ts +42 -0
- package/lib/cargo.d.ts.map +1 -1
- package/lib/cargo.js +2 -0
- package/lib/cargo.js.map +1 -1
- package/lib/cascade.d.ts.map +1 -1
- package/lib/cascade.js +19 -1
- package/lib/cascade.js.map +1 -1
- package/lib/commands.d.ts.map +1 -1
- package/lib/commands.js +65 -4
- package/lib/commands.js.map +1 -1
- package/lib/config.d.ts +16 -1
- package/lib/config.d.ts.map +1 -1
- package/lib/config.js +8 -0
- package/lib/config.js.map +1 -1
- package/lib/hooks-map.d.ts +13 -0
- package/lib/hooks-map.d.ts.map +1 -1
- package/lib/hooks-map.js +33 -1
- package/lib/hooks-map.js.map +1 -1
- package/lib/observations.d.ts +35 -1
- package/lib/observations.d.ts.map +1 -1
- package/lib/observations.js +14 -2
- package/lib/observations.js.map +1 -1
- package/lib/ship.d.ts +2 -0
- package/lib/ship.d.ts.map +1 -1
- package/lib/ship.js +2 -0
- package/lib/ship.js.map +1 -1
- package/lib/thresholds.d.ts +49 -0
- package/lib/thresholds.d.ts.map +1 -0
- package/lib/thresholds.js +151 -0
- package/lib/thresholds.js.map +1 -0
- package/package.json +1 -1
- package/rt-tools-agent-kit-0.12.0.tgz +0 -0
- package/assets/commands/agent-kit-digest.md +0 -88
- package/assets/commands/rules-review.md +0 -98
- package/rt-tools-agent-kit-0.10.0.tgz +0 -0
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
name: git-workflow-commit
|
|
3
3
|
kind: pattern
|
|
4
4
|
rule: git-workflow
|
|
5
|
-
description: Паттерн правила git-workflow
|
|
5
|
+
description: Паттерн правила git-workflow. Брать на заведение рабочего элемента, ветки, коммит и пуш — заведение элемента с областью и итерацией, перевод состояния, слияние двух задач в одну, работа от учётной записи машинной работы, обход требования документа. Не брать на открытие PR — это паттерн git-workflow-pr; не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
#
|
|
8
|
+
# Задача, ветка и коммит
|
|
9
9
|
|
|
10
10
|
Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
|
|
11
11
|
`docs/constitution/delivery.md`.
|
|
@@ -15,7 +15,6 @@ description: Паттерн правила git-workflow для дерева в A
|
|
|
15
15
|
- Заводится рабочий элемент, с которого начинается правка.
|
|
16
16
|
- Заводится ветка под него.
|
|
17
17
|
- Готовится коммит или пуш.
|
|
18
|
-
- Открывается PR.
|
|
19
18
|
- Работа перешла на следующий шаг, и элемент переводится в другое состояние.
|
|
20
19
|
|
|
21
20
|
## Сначала рабочий элемент, потом ветка
|
|
@@ -150,212 +149,13 @@ GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<почта бота>" \
|
|
|
150
149
|
Docs-skip: правка только в тестах хука, зеркала у него нет
|
|
151
150
|
```
|
|
152
151
|
|
|
153
|
-
## Номер элемента стоит в его заголовке и в заголовке PR
|
|
154
|
-
|
|
155
|
-
Форма одна на оба — `[<номер>] <текст>`. Номер стоит в самом заголовке, а не только в теле: в
|
|
156
|
-
списке PR тела не видно. Тот же номер несёт и имя ветки, поэтому элемент, ветка и PR читаются
|
|
157
|
-
как одно.
|
|
158
|
-
|
|
159
|
-
Элемент говорит, что не так; PR тем же номером отчитывается, что сделано:
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
элемент [86] Пустой адрес владельца — письма не уходят молча
|
|
163
|
-
PR [86] Письмо владельцу с незаполненным адресом попадает в логи
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
Инфинитив в заголовок PR не переносится: «исправить» становится «исправлено», «вернуть» —
|
|
167
|
-
«возвращено», «добавить» — «добавлено».
|
|
168
|
-
|
|
169
|
-
Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
|
|
170
|
-
коммита, и там его сверяет `commitlint`.
|
|
171
|
-
|
|
172
|
-
## Не готовое к слиянию открывается черновиком
|
|
173
|
-
|
|
174
|
-
Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
|
|
175
|
-
PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
|
|
176
|
-
черновиком — завершение у черновика хостинг блокирует сам:
|
|
177
|
-
|
|
178
|
-
```bash
|
|
179
|
-
AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create --draft true --title '[<КЛЮЧ>-86] …' \
|
|
180
|
-
--description "$(cat тело.md)"
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
Конвейер проверок у черновика по умолчанию не запускается: молчание прогона за зелёный прогон
|
|
184
|
-
не принимается, и набор гоняется на своей машине либо запуском вручную.
|
|
185
|
-
|
|
186
|
-
Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
|
|
187
|
-
задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
|
|
188
|
-
захода.
|
|
189
|
-
|
|
190
|
-
Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
|
|
191
|
-
решение готово:
|
|
192
|
-
|
|
193
|
-
```bash
|
|
194
|
-
AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr update --id 86 --draft false
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
|
|
198
|
-
черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
|
|
199
|
-
ждёт разбора ровно так же, как не снятый.
|
|
200
|
-
|
|
201
|
-
## PR привязывается к элементу при создании
|
|
202
|
-
|
|
203
|
-
Привязка задаётся флагом, а не правкой после: у токена может не быть права править чужой
|
|
204
|
-
элемент, и вторая команда обойдётся молча, оставив PR ни с чем не связанным.
|
|
205
|
-
|
|
206
|
-
```bash
|
|
207
|
-
AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create \
|
|
208
|
-
--title '[86] Письмо владельцу с незаполненным адресом попадает в логи' \
|
|
209
|
-
--source-branch 86-mail-owner-silence --target-branch main \
|
|
210
|
-
--work-items 86 --reviewers <владелец> --delete-source-branch true \
|
|
211
|
-
--description 'Закрывает рабочий элемент 86.'
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Один PR
|
|
215
|
-
закрывает элемент целиком — половину задачи одним PR не выкатывают: у задачи одна ветка, и
|
|
216
|
-
работа, которая в неё не влезает, делится на задачи до того, как ветка заводится.
|
|
217
|
-
|
|
218
|
-
У уже открытого PR то же ставится правкой:
|
|
219
|
-
|
|
220
|
-
```bash
|
|
221
|
-
az repos pr work-item add --id 205 --work-items 86
|
|
222
|
-
az repos pr reviewer add --id 205 --reviewers <владелец>
|
|
223
|
-
az repos pr update --id 205 --description "$(cat тело.md)"
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
Правка описания переписывает его целиком. Тело перечитывается всякий раз, когда в ветку что-то
|
|
227
|
-
влилось после публикации: PR утверждает про дерево, а дерево с тех пор изменилось.
|
|
228
|
-
|
|
229
|
-
## Образец тела PR
|
|
230
|
-
|
|
231
|
-
Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
|
|
232
|
-
оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
|
|
233
|
-
заголовок читаются одинаково, а значат разное.
|
|
234
|
-
|
|
235
|
-
```markdown
|
|
236
|
-
Закрывает рабочий элемент 86.
|
|
237
|
-
|
|
238
|
-
## Что сделано
|
|
239
|
-
|
|
240
|
-
- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
|
|
241
|
-
|
|
242
|
-
## Чем подтверждено
|
|
243
|
-
|
|
244
|
-
- <проверка>: <её вывод одной строкой>
|
|
245
|
-
- Не гонялось: <что в набор не вошло и почему>
|
|
246
|
-
|
|
247
|
-
## Оставшийся шаг
|
|
248
|
-
|
|
249
|
-
После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
|
|
250
|
-
вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
|
|
254
|
-
— в тот ход, которым папка разбирается и снимается черновик:
|
|
255
|
-
|
|
256
|
-
```markdown
|
|
257
|
-
## Оставшийся шаг
|
|
258
|
-
|
|
259
|
-
Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
|
|
263
|
-
сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
|
|
264
|
-
не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
|
|
265
|
-
|
|
266
|
-
Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
|
|
267
|
-
заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
|
|
268
|
-
|
|
269
|
-
## Состояние PR читается, а не додумывается
|
|
270
|
-
|
|
271
|
-
Команды правки отвечают нулевым кодом и тогда, когда ничего не сделали. Поэтому после них PR
|
|
272
|
-
перечитывают:
|
|
273
|
-
|
|
274
|
-
```bash
|
|
275
|
-
az repos pr show --id 205 \
|
|
276
|
-
--query '{author: createdBy.uniqueName, reviewers: reviewers[].uniqueName, work: workItemRefs[].id}'
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
Владельцу называют то, что прочитали, а не то, что заказывали.
|
|
280
|
-
|
|
281
|
-
Перечитывают его и по времени, а не только после вызовов, которые молча ничего не сделали:
|
|
282
|
-
состояние PR читается перед тем, как что-либо о нём сказать. Между «прогон зелёный» и следующей
|
|
283
|
-
фразой владелец успевает влить PR, и всё сказанное о нём после этого — про вчерашний день. Так
|
|
284
|
-
владельцу и было предложено влить то, что он влил часом раньше.
|
|
285
|
-
|
|
286
|
-
Открытый PR означает, что элемент ждёт разбора, — состояние переставляется тем же движением:
|
|
287
|
-
|
|
288
|
-
```bash
|
|
289
|
-
npm run task:move -- 86 in-review
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
## Что проверяется до публикации PR
|
|
293
|
-
|
|
294
|
-
Конвейер видит только отправленное, а отправляется оно пушем. Линтеры, юниты и сценарии хуков
|
|
295
|
-
снимает гейт пуша — ниже то, чего он не знает.
|
|
296
|
-
|
|
297
|
-
1. **Главная ветка влита в эту ветку** — `git fetch origin && git merge origin/main`.
|
|
298
|
-
Всё, что проверяется ниже, проверяется от этого основания: PR с разошедшейся ветки
|
|
299
|
-
показывает ревьюверу правку вперемешку с чужой. Порядок и разбор конфликта — паттерн
|
|
300
|
-
`git-workflow-merge`.
|
|
301
|
-
2. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
|
|
302
|
-
домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
|
|
303
|
-
3. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
|
|
304
|
-
целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
|
|
305
|
-
4. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
|
|
306
|
-
поведения он не знает — это остаётся за автором.
|
|
307
|
-
5. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`. Какие именно
|
|
308
|
-
есть здесь — `implementation.md` правила.
|
|
309
|
-
6. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет.
|
|
310
|
-
7. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
|
|
311
|
-
переводится.
|
|
312
|
-
8. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
|
|
313
|
-
`browser-verification-measure`.
|
|
314
|
-
9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
|
|
315
|
-
паттерн `seo-verify`.
|
|
316
|
-
10. **PR привязан к рабочему элементу**, ревьювер и исполнитель стоят, а тело собрано по
|
|
317
|
-
образцу — разделы «Что сделано», «Чем подтверждено» и «Оставшийся шаг». Раздел оставшегося
|
|
318
|
-
шага к этому моменту говорит, что шагов не осталось: черновик снимается после разбора
|
|
319
|
-
папки, а не до него.
|
|
320
|
-
11. **Заголовок PR несёт номер элемента и называет работу сделанной:** `[<номер>] <Что
|
|
321
|
-
сделано>`, тем же номером, что стоит у элемента и в имени ветки.
|
|
322
|
-
12. **Очередь работ сходится** — `npm run check:board`.
|
|
323
|
-
13. **Состояние PR прочитано, а не выведено из кодов возврата.**
|
|
324
|
-
14. **Набор взят из файла конвейера, а не собран по памяти.** Гейт пуша заведомо уже: он стоит
|
|
325
|
-
между командой и пушем, и всё, что дольше секунд, из него вынесено. Что гоняет конвейер,
|
|
326
|
-
написано в его файле — этот список и повторяется локально; зелёный гейт полнотой набора не
|
|
327
|
-
является.
|
|
328
|
-
15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
|
|
329
|
-
теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
|
|
330
|
-
снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
|
|
331
|
-
PR.
|
|
332
|
-
|
|
333
|
-
Сразу после публикации элемент переводится в разбор, и сверка очереди прогоняется ещё раз: до
|
|
334
|
-
открытия PR состояние она не судит, а после открытия расхождение видит.
|
|
335
|
-
|
|
336
|
-
Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
|
|
337
|
-
названное проверенным, ревьювер принимает за проверенное.
|
|
338
|
-
|
|
339
|
-
**Раздел «Чем подтверждено» называет и то, что не гонялось.** Список одного прогнанного
|
|
340
|
-
неотличим от полного набора, и ревьювер по нему решает, что можно не перепроверять. Цена ошибки
|
|
341
|
-
здесь не красный конвейер, а доверие к разделу: однажды прочитанный как полнота, дальше он
|
|
342
|
-
перепроверяется весь.
|
|
343
|
-
|
|
344
152
|
## Частые промахи
|
|
345
153
|
|
|
346
154
|
- Область и итерация не заданы: элемент заведён, но на доску команды не попал.
|
|
347
155
|
- Состояние взято не из процесса проекта: перевод отвечает отказом на каждой задаче, и это
|
|
348
156
|
читается как сломанная команда, а не как неверное имя состояния.
|
|
349
|
-
- PR открыт без `--work-items`: связи нет, и по очереди работ не видно, за чем эта правка.
|
|
350
|
-
- `AB#<номер>` в коммите принят за привязку PR: он связывает коммит, а очередь читает связь PR.
|
|
351
157
|
- `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
|
|
352
158
|
команда обрывается на первом промахе целиком. Следующий `git commit --amend` при этом уносит
|
|
353
159
|
в коммит всё, что осталось в индексе. Состав коммита читается `git show --stat` сразу после
|
|
354
160
|
него, а не на разборе PR.
|
|
355
|
-
- PR открыт без ревьювера: он не попадает во входящие владельца, и очередь стоит, выглядя
|
|
356
|
-
работающей.
|
|
357
|
-
- `--delete-source-branch` забыт: ветки задач копятся в репозитории, и по списку веток больше
|
|
358
|
-
не видно, какая работа идёт сейчас.
|
|
359
|
-
- Автозавершение включено до того, как прогнаны проверки до пуша: конвейер зелёный на том, что
|
|
360
|
-
он умеет, и слияние происходит без всего остального.
|
|
361
161
|
- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.
|
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
name: git-workflow-commit
|
|
3
3
|
kind: pattern
|
|
4
4
|
rule: git-workflow
|
|
5
|
-
description: Паттерн правила git-workflow. Брать на заведение задачи, ветки,
|
|
5
|
+
description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит и пуш — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы, слияние двух задач в одну, работа от учётной записи бота, обход требования документа. Не брать на открытие PR — это паттерн git-workflow-pr; не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
#
|
|
8
|
+
# Задача, ветка и коммит
|
|
9
9
|
|
|
10
10
|
Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
|
|
11
11
|
`docs/constitution/delivery.md`.
|
|
@@ -15,7 +15,6 @@ description: Паттерн правила git-workflow. Брать на зав
|
|
|
15
15
|
- Заводится задача, с которой начинается правка.
|
|
16
16
|
- Заводится ветка под задачу.
|
|
17
17
|
- Готовится коммит или пуш.
|
|
18
|
-
- Открывается PR.
|
|
19
18
|
- Работа перешла на следующий шаг, и задача переставляется в другую колонку борды.
|
|
20
19
|
|
|
21
20
|
## Сначала задача на борде, потом ветка
|
|
@@ -161,250 +160,6 @@ chore(deploy): docker-compose for vps
|
|
|
161
160
|
Docs-skip: правка только в тестах хука, зеркала у него нет
|
|
162
161
|
```
|
|
163
162
|
|
|
164
|
-
## Номер задачи стоит в её заголовке и в заголовке PR
|
|
165
|
-
|
|
166
|
-
Форма одна на оба — `[<КЛЮЧ>-<номер>] <текст>`. Номер стоит в самом заголовке, а не только в
|
|
167
|
-
теле: в списке PR тела не видно, а в списке задач номер иначе приходится искать глазами по
|
|
168
|
-
колонке слева. Тот же номер несёт и имя ветки — `<КЛЮЧ>-<номер>-<короткий-slug>`, — поэтому
|
|
169
|
-
задача, ветка и PR читаются как одно.
|
|
170
|
-
|
|
171
|
-
Задача говорит, что не так; PR тем же номером отчитывается, что сделано:
|
|
172
|
-
|
|
173
|
-
```
|
|
174
|
-
задача [<КЛЮЧ>-86] Пустой MAIL_OWNER — письма владельцу не уходят молча
|
|
175
|
-
PR [<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи
|
|
176
|
-
|
|
177
|
-
задача [<КЛЮЧ>-101] Вернуть оверлей загрузки таблицы и включить stylelint гейтом
|
|
178
|
-
PR [<КЛЮЧ>-101] Stylelint включён гейтом
|
|
179
|
-
|
|
180
|
-
задача [<КЛЮЧ>-212] Сайт не собирается: компонентам кита проставлен префикс приложения вместо своего
|
|
181
|
-
PR [<КЛЮЧ>-212] Виджет переписки зовёт кит его собственными именами
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
Инфинитив из задачи в заголовок PR не переносится: «исправить» становится «исправлено»,
|
|
185
|
-
«вернуть» — «возвращено», «добавить» — «добавлено».
|
|
186
|
-
|
|
187
|
-
Номер в заголовке обязан совпасть с номером ветки: гард поставки сверяет их до отправки
|
|
188
|
-
команды, а сверка очереди — у каждого открытого PR.
|
|
189
|
-
|
|
190
|
-
Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
|
|
191
|
-
коммита, и там его сверяет `commitlint`. В списке PR он занимает место, ничего не добавляя:
|
|
192
|
-
род правки и область уже видны метками.
|
|
193
|
-
|
|
194
|
-
## Не готовое к слиянию открывается черновиком
|
|
195
|
-
|
|
196
|
-
Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
|
|
197
|
-
PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
|
|
198
|
-
черновиком — кнопку слияния у черновика хостинг блокирует сам:
|
|
199
|
-
|
|
200
|
-
```bash
|
|
201
|
-
GH_TOKEN="$TOKEN" gh pr create --draft --title '[<КЛЮЧ>-86] …' --body-file тело.md
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
|
|
205
|
-
задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
|
|
206
|
-
захода.
|
|
207
|
-
|
|
208
|
-
Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
|
|
209
|
-
решение готово:
|
|
210
|
-
|
|
211
|
-
```bash
|
|
212
|
-
GH_TOKEN="$TOKEN" gh pr ready 86
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
|
|
216
|
-
черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
|
|
217
|
-
ждёт разбора ровно так же, как не снятый.
|
|
218
|
-
|
|
219
|
-
## PR прикрепляется к задаче
|
|
220
|
-
|
|
221
|
-
Тело начинается со строки связи — по ней на борде заполняется поле «Linked pull requests».
|
|
222
|
-
Ревьювер, исполнитель и метки задаются той же командой, и PR без них не открывается:
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
GH_TOKEN="$TOKEN" gh pr create --title '[<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи' \
|
|
226
|
-
--reviewer <владелец> --assignee <бот> --label bug --label area:api \
|
|
227
|
-
--body 'Closes #86
|
|
228
|
-
|
|
229
|
-
…'
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Исполнитель —
|
|
233
|
-
та же учётная запись, от которой идёт машинная работа. Метки берутся у задачи целиком — и род
|
|
234
|
-
правки, и все её области; читаются они у задачи, а не выбираются по памяти:
|
|
235
|
-
|
|
236
|
-
```bash
|
|
237
|
-
/opt/homebrew/bin/gh issue view 86 --json labels --jq '.labels | map(.name) | join(",")'
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
Строка `Closes #<номер>` обязательна: без неё PR не прикрепляется к задаче, и сверка очереди
|
|
241
|
-
это находит. Она же и означает, что задача закрывается целиком — половину задачи одним PR не
|
|
242
|
-
выкатывают: у задачи одна ветка, и работа, которая в неё не влезает, делится на задачи до
|
|
243
|
-
того, как ветка заводится.
|
|
244
|
-
|
|
245
|
-
У уже открытого PR то же ставится тремя вызовами REST. `gh pr edit` здесь не годится: он
|
|
246
|
-
запрашивает карточки Projects (classic), получает отказ о снятом API и до правки не доходит.
|
|
247
|
-
|
|
248
|
-
```bash
|
|
249
|
-
GH=/opt/homebrew/bin/gh
|
|
250
|
-
REPO=<владелец>/<репозиторий>
|
|
251
|
-
|
|
252
|
-
$GH api -X POST "repos/$REPO/issues/205/labels" -f 'labels[]=bug' -f 'labels[]=area:api'
|
|
253
|
-
$GH api -X POST "repos/$REPO/issues/205/assignees" -f 'assignees[]=<бот>'
|
|
254
|
-
$GH api -X POST "repos/$REPO/pulls/205/requested_reviewers" -f 'reviewers[]=<владелец>'
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
Тем же вызовом правится и само тело: `-f body=` переписывает его целиком, поэтому строка
|
|
258
|
-
`Closes #<номер>` пишется заново вместе с остальным текстом.
|
|
259
|
-
|
|
260
|
-
```bash
|
|
261
|
-
$GH api -X PATCH "repos/$REPO/pulls/205" -f body="$(cat тело.md)"
|
|
262
|
-
```
|
|
263
|
-
|
|
264
|
-
Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: PR
|
|
265
|
-
утверждает про дерево, а дерево с тех пор изменилось.
|
|
266
|
-
|
|
267
|
-
## Образец тела PR
|
|
268
|
-
|
|
269
|
-
Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
|
|
270
|
-
оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
|
|
271
|
-
заголовок читаются одинаково, а значат разное.
|
|
272
|
-
|
|
273
|
-
```markdown
|
|
274
|
-
Closes #86
|
|
275
|
-
|
|
276
|
-
## Что сделано
|
|
277
|
-
|
|
278
|
-
- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
|
|
279
|
-
|
|
280
|
-
## Чем подтверждено
|
|
281
|
-
|
|
282
|
-
- <проверка>: <её вывод одной строкой>
|
|
283
|
-
- Не гонялось: <что в набор не вошло и почему>
|
|
284
|
-
|
|
285
|
-
## Оставшийся шаг
|
|
286
|
-
|
|
287
|
-
После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
|
|
288
|
-
вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
|
|
292
|
-
— в тот ход, которым папка разбирается и снимается черновик:
|
|
293
|
-
|
|
294
|
-
```markdown
|
|
295
|
-
## Оставшийся шаг
|
|
296
|
-
|
|
297
|
-
Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
|
|
301
|
-
сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
|
|
302
|
-
не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
|
|
303
|
-
|
|
304
|
-
Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
|
|
305
|
-
заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
|
|
306
|
-
|
|
307
|
-
## Состояние PR читается, а не додумывается
|
|
308
|
-
|
|
309
|
-
Вызовы, которыми ставятся ревьювер, метки и исполнитель, отвечают нулевым кодом и тогда, когда
|
|
310
|
-
ничего не сделали: запрос разбора на автора PR GitHub молча выбрасывает. Поэтому после них PR
|
|
311
|
-
перечитывают:
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
# Ключи латиницей: кириллический ключ без кавычек `jq` не разбирает и падает на нём
|
|
315
|
-
$GH api "repos/$REPO/pulls/321" \
|
|
316
|
-
--jq '{author: .user.login, reviewers: [.requested_reviewers[].login], labels: [.labels[].name]}'
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
Автор здесь — `<бот>`. Если им оказался владелец, ревьювера у PR не будет вовсе:
|
|
320
|
-
назначить автора ревьювером нельзя, а отказа на такой запрос не приходит. Владельцу называют
|
|
321
|
-
то, что прочитали, а не то, что заказывали.
|
|
322
|
-
|
|
323
|
-
Учётная запись, из-под которой пришлось пушить, в этот вызов не переносится: пуш и авторство
|
|
324
|
-
PR выбираются отдельно, и `GH_TOKEN` для публикации — всегда токен бота.
|
|
325
|
-
|
|
326
|
-
Перечитывают его и по времени, а не только после вызовов, которые молча ничего не сделали:
|
|
327
|
-
состояние PR читается перед тем, как что-либо о нём сказать. Между «прогон зелёный» и следующей
|
|
328
|
-
фразой владелец успевает влить PR, и всё сказанное о нём после этого — про вчерашний день. Так
|
|
329
|
-
владельцу и было предложено влить то, что он влил часом раньше.
|
|
330
|
-
|
|
331
|
-
Открытый PR означает, что задача ждёт разбора, — колонка переставляется тем же движением:
|
|
332
|
-
|
|
333
|
-
```bash
|
|
334
|
-
npm run task:move -- 86 in-review
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
Голым GraphQL по идентификаторам проекта, элемента и варианта поля это не пишется: команда
|
|
338
|
-
знает их сама, а собранный по памяти запрос молча ставит не ту колонку — отказа у борды на
|
|
339
|
-
это нет.
|
|
340
|
-
|
|
341
|
-
## Что проверяется до публикации PR
|
|
342
|
-
|
|
343
|
-
Проверок на самом PR нет: выкатка запускается пушем в главную ветку, и до мержа никто не
|
|
344
|
-
гоняет ничего. Линтеры, юниты и сценарии хуков снимает гейт пуша — ниже то, чего он не знает.
|
|
345
|
-
|
|
346
|
-
1. **Главная ветка влита в эту ветку** — `git fetch origin && git merge origin/main`.
|
|
347
|
-
Свежесть основания между ветками одного захода не наследуется: вторая и третья ветка
|
|
348
|
-
отводятся после своего `fetch`, а не от ссылки, подтянутой под первую. Пока идёт работа,
|
|
349
|
-
главная уходит вперёд — чаще всего собственным PR того же исполнителя, влитым час
|
|
350
|
-
назад.
|
|
351
|
-
Всё, что проверяется ниже, проверяется от этого основания: PR с разошедшейся ветки
|
|
352
|
-
показывает ревьюверу правку вперемешку с чужой. Порядок и разбор конфликта — паттерн
|
|
353
|
-
`git-workflow-merge`.
|
|
354
|
-
2. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
|
|
355
|
-
домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
|
|
356
|
-
3. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
|
|
357
|
-
целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
|
|
358
|
-
4. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
|
|
359
|
-
поведения он не знает — это остаётся за автором.
|
|
360
|
-
5. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`: сверка
|
|
361
|
-
сценариев с тестами, путей в документах, раскладки либ, повторов и классов без правила.
|
|
362
|
-
Какие именно есть здесь — `implementation.md` правила.
|
|
363
|
-
6. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет:
|
|
364
|
-
она длиннее всего, что он успевает сделать между командой и пушем.
|
|
365
|
-
7. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
|
|
366
|
-
переводится.
|
|
367
|
-
8. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
|
|
368
|
-
`browser-verification-measure`.
|
|
369
|
-
9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** — паттерн
|
|
370
|
-
`seo-verify`.
|
|
371
|
-
10. **Тело PR собрано по образцу** — начинается строкой `Closes #<номер>`, несёт разделы «Что
|
|
372
|
-
сделано», «Чем подтверждено» и «Оставшийся шаг», а метки, ревьювер и исполнитель стоят.
|
|
373
|
-
Раздел оставшегося шага к этому моменту говорит, что шагов не осталось: черновик снимается
|
|
374
|
-
после разбора папки, а не до него.
|
|
375
|
-
11. **Заголовок PR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что сделано>`,
|
|
376
|
-
тем же номером, что стоит у задачи и в имени ветки. Инфинитив из задачи в него не
|
|
377
|
-
переносится, тип и область коммита — тоже.
|
|
378
|
-
12. **Очередь работ сходится** — `npm run check:board`. Задача на борде, с исполнителем и
|
|
379
|
-
номером в заголовке; PR один на задачу, и закрывает он её целиком.
|
|
380
|
-
13. **Состояние PR прочитано, а не выведено из кодов возврата** — автор `<бот>`,
|
|
381
|
-
ревьювер — владелец, метки те же, что у задачи. Владельцу называют прочитанное.
|
|
382
|
-
14. **Набор взят из файла конвейера, а не собран по памяти.** Гейт пуша заведомо уже: он стоит
|
|
383
|
-
между командой и пушем, и всё, что дольше секунд, из него вынесено. Что гоняет конвейер,
|
|
384
|
-
написано в его файле — этот список и повторяется локально; зелёный гейт полнотой набора не
|
|
385
|
-
является.
|
|
386
|
-
15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
|
|
387
|
-
теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
|
|
388
|
-
снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
|
|
389
|
-
PR.
|
|
390
|
-
|
|
391
|
-
Список этот — про снятие черновика, а не про его открытие. Черновиком PR открывается раньше:
|
|
392
|
-
пока работа идёт, человеку показывают то, что уже есть, вместе с тем, чего ещё нет. Пункты 1–15
|
|
393
|
-
проходятся перед `gh pr ready`, и невыполненный пункт означает, что черновик не снимается, — а
|
|
394
|
-
не то, что PR не открывается.
|
|
395
|
-
|
|
396
|
-
Сразу после публикации задача переставляется в разбор — `npm run task:move -- <номер>
|
|
397
|
-
in-review`, — и `npm run check:board` прогоняется ещё раз: до открытия PR колонку он не судит,
|
|
398
|
-
а после открытия расхождение видит.
|
|
399
|
-
|
|
400
|
-
Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
|
|
401
|
-
названное проверенным, ревьювер принимает за проверенное.
|
|
402
|
-
|
|
403
|
-
**Раздел «Чем подтверждено» называет и то, что не гонялось.** Список одного прогнанного
|
|
404
|
-
неотличим от полного набора, и ревьювер по нему решает, что можно не перепроверять. Цена ошибки
|
|
405
|
-
здесь не красный конвейер, а доверие к разделу: однажды прочитанный как полнота, дальше он
|
|
406
|
-
перепроверяется весь.
|
|
407
|
-
|
|
408
163
|
## Частые промахи
|
|
409
164
|
|
|
410
165
|
- `gh` в оболочке пользователя подменён — звать `/opt/homebrew/bin/gh` напрямую.
|
|
@@ -431,15 +186,4 @@ in-review`, — и `npm run check:board` прогоняется ещё раз:
|
|
|
431
186
|
ловит и сверка — ей ветка тоже не видна.
|
|
432
187
|
- `gh api graphql --paginate` на запросе элементов борды уходит в повтор первой страницы:
|
|
433
188
|
курсор берётся из ответа руками, а полнота сверяется с `items(first: 1) { totalCount }`.
|
|
434
|
-
- Второй строкой `Closes` в одном PR задача больше не закрывается: две задачи в одной ветке
|
|
435
|
-
откатываются только вместе. Либо это одна задача — и вторая поглощается, — либо две ветки.
|
|
436
|
-
- Половина задачи, уехавшая своим PR, тоже промах: тело такого PR начинается со слов «Часть
|
|
437
|
-
#<номер>» вместо `Closes`, задача остаётся открытой, и после отката видно её целой. Работа,
|
|
438
|
-
которая в одну ветку не влезает, делится на задачи до того, как ветка заводится.
|
|
439
|
-
- PR открыт без ревьювера: он не попадает во входящие владельца вовсе, и очередь стоит,
|
|
440
|
-
выглядя работающей. Так шестнадцать PR ждали разбора, которого никто не запрашивал.
|
|
441
|
-
- Метки поставлены по названию PR, а не прочитаны у задачи: область теряется, и по борде не
|
|
442
|
-
видно, что правка задела ещё и сайт.
|
|
443
|
-
- Задача закрыта не полностью, а метки перенесены целиком: тикет остаётся открытым, и это
|
|
444
|
-
говорится в теле PR, а не подразумевается строкой `Closes`.
|
|
445
189
|
- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.
|