From 3b0c846cf6bb069d12db676294989c9bd95a3615 Mon Sep 17 00:00:00 2001 From: BrowenSiz Date: Sun, 8 Nov 2026 18:34:20 +0300 Subject: [PATCH] =?UTF-8?q?chore:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D0=BF=D1=80=D0=B0=D0=B2=D0=B8=D0=BB=D0=B0?= =?UTF-8?q?=20git,=20=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD=20PR=20=D0=B8=20?= =?UTF-8?q?=D0=BF=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D0=BE=D1=87=D0=BD=D1=8B?= =?UTF-8?q?=D0=B5=20=D1=85=D1=83=D0=BA=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Правила работы с ветками, коммитами и PR в docs/contributing.md. Lefthook проверяет формат коммита, форматирует Go и ищет секреты перед коммитом. Refs: 1.2.8, 1.2.9, 1.2.10, 1.13.4 Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- .gitea/pull_request_template.md | 25 ++++++ .mise.toml | 2 + AGENTS.md | 1 + docs/contributing.md | 83 +++++++++++++++++++ docs/environment.md | 5 +- .../2026-11-08-shared-1.2-git-rules.md | 36 ++++++++ docs/status/shared.md | 1 + lefthook.yml | 18 ++++ tools/git-hooks/commit-msg.mjs | 32 +++++++ 9 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 .gitea/pull_request_template.md create mode 100644 docs/contributing.md create mode 100644 docs/journal/2026-11-08-shared-1.2-git-rules.md create mode 100644 lefthook.yml create mode 100644 tools/git-hooks/commit-msg.mjs diff --git a/.gitea/pull_request_template.md b/.gitea/pull_request_template.md new file mode 100644 index 0000000..fd29a4c --- /dev/null +++ b/.gitea/pull_request_template.md @@ -0,0 +1,25 @@ + + +**Задача:** # +**Пункты:** + +## Что сделано +- + +## Как проверить +1. + +## Скриншоты + + +## Чек-лист +- [ ] Коммиты и название PR по-русски, в каждом коммите есть `Refs:` +- [ ] Ветка свежая: `git rebase origin/main`, конфликтов нет +- [ ] Запросы к данным организации — с `tenant_id` и через `WithTenantTx` +- [ ] Права проверяются на сервере (`access.Require` / `ScopesFor`), интерфейс только скрывает +- [ ] Новая функция — за флагом из каталога функций +- [ ] Миграции только новые, смерженные не изменены; контракты (`api/`, `proto/`, `migrations/`) — отдельным PR +- [ ] Тесты добавлены или обновлены; для новой таблицы организации — тест изоляции +- [ ] Секретов и персональных данных в коде, логах и документах нет +- [ ] Документация обновлена: запись журнала, `docs/status/`, ADR при значимом решении +- [ ] Ссылка на этот PR добавлена в «Ссылки» задачи в дорожной карте diff --git a/.mise.toml b/.mise.toml index c231c8d..eb871c3 100644 --- a/.mise.toml +++ b/.mise.toml @@ -4,3 +4,5 @@ go = "1.27.3" node = "26.13.0" pnpm = "12.17.0" task = "3.54.0" +lefthook = "2.2.2" +gitleaks = "8.30.1" diff --git a/AGENTS.md b/AGENTS.md index 90388c4..2fcea58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -122,6 +122,7 @@ shtil-roadmap.html дорожная карта - Хорошо: `feat(server): добавлен WithTenantTx для доступа к данным организации`, `fix(console): исправлен повтор запроса после истечения токена`. - Плохо: `fix`, `правки`, `update files`, `WIP`, английский текст. - Заголовок squash-коммита при слиянии PR тоже по-русски, обычно совпадает с названием PR. + - Формат проверяет хук `commit-msg` (lefthook), `--no-verify` не используется. Полные правила git — `docs/contributing.md`, описание PR — по шаблону `.gitea/pull_request_template.md`. - Изменения `api/openapi.yaml`, `proto/`, `migrations/` — отдельным PR. - Значимое техническое решение — ADR в `docs/adr/NNNN-название.md` и поле «Решение» в дорожной карте. - Без лишних комментариев: комментарий объясняет «почему», а не «что». diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..8a571f8 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,83 @@ +# Как мы работаем с git + +Задача #1.2. Кратко для AI — `AGENTS.md`, раздел 6. Здесь — полная версия для людей. + +## Главное +- `main` — общая рабочая версия продукта. Всегда собирается и работает. Напрямую в неё не пушим. +- Одна задача — одна короткая ветка (1–3 дня) → PR → ревью второго → **squash**-слияние → ветка удаляется. +- Файлы друг друга получаем только через `main`: после слияния `git pull`. +- Задачи, статусы и обсуждения — в дорожной карте. ID задачи есть в ветке, коммитах и PR. + +## Первый запуск +``` +git clone https://locshare.ru/TMSH/shtil.git +cd shtil +mise trust && mise install # версии инструментов, docs/environment.md +lefthook install # git-хуки: проверка коммитов и секретов +``` + +## Ветки +| Вид | Формат | Пример | +|---|---|---| +| Новая функция | `feat/-кратко` | `feat/2.13-design-tokens` | +| Исправление | `fix/-кратко` | `fix/2.14-token-refresh` | +| Документы | `docs/-кратко` | `docs/1.11-information-architecture` | +| Служебное | `chore/-кратко` | `chore/2.9-ci` | + +Имя ветки — латиницей через дефис. Ветка живёт не дольше 3 дней; незаконченное прячется за техническим флагом функции и сливается. + +## Коммиты +Формат — Conventional Commits, текст **по-русски**: +``` +тип(область): что сделано + +Почему так и что важно знать (если нужно). + +Refs: 2.11.4 +``` +- **Типы:** `feat` новое · `fix` исправление · `docs` документы · `refactor` переделка без изменения поведения · `test` тесты · `perf` скорость · `build` сборка · `ci` CI и окружение · `chore` прочее служебное · `style` форматирование · `revert` откат. +- **Области:** `server` `agent` `helper` `console` `ui` `proto` `api` `db` `ci` `docs` `roadmap` `tools` `deps`. Область можно не указывать, если изменение общее. +- Заголовок с маленькой буквы, без точки, до 72 символов, глагол в прошедшем времени: «добавлен», «исправлена», «убрано». +- `Refs:` — ID пунктов дорожной карты через запятую. +- Коммиты маленькие: один коммит — одно законченное изменение. + +| Хорошо | Плохо | +|---|---| +| `feat(server): добавлен WithTenantTx для доступа к данным организации` | `правки` | +| `fix(console): исправлен повтор запроса после истечения токена` | `fix bug` | +| `docs(ui): описаны цветовые токены и темы` | `WIP` | + +Формат проверяет хук `commit-msg` (`tools/git-hooks/commit-msg.mjs`). Обходить его (`--no-verify`) нельзя. + +## Каждый день +``` +git switch main && git pull # начало задачи +git switch -c feat/2.13-design-tokens + +git add . && git commit # по ходу работы + +git fetch && git rebase origin/main # каждое утро и перед PR +git push -u origin feat/2.13-design-tokens # первый раз +git push --force-with-lease # после rebase, только в свою ветку +``` +Конфликт при rebase решается у себя: исправить файлы → `git add` → `git rebase --continue`. + +## Pull Request +1. Название: `[ID] Что сделано`, по-русски. Описание заполняется по шаблону, текст «Выполнение» можно взять кнопкой «Для PR» в задаче карты. +2. Рецензент — второй разработчик. Ревью — в тот же день. +3. Слияние — кнопкой **squash** (другие способы отключены). Заголовок итогового коммита — как название PR, в формате коммита. Ветка удаляется автоматически. +4. Ссылка на PR — в «Ссылки» задачи карты, отмечены выполненные пункты. +5. Оба делают `git pull` в `main`. + +Изменения `api/openapi.yaml`, `proto/`, `migrations/` — отдельным маленьким PR с обсуждением, до реализации. + +## Нельзя +- Пушить в `main` и делать `force push` в `main` или чужую ветку. +- Сливать PR без одобрения второго разработчика и при красном CI (после #2.9). +- Редактировать смерженную миграцию — только новая миграция. +- Коммитить секреты, `.env`, ключи. Нашли секрет в истории — сразу сообщить второму, секрет перевыпустить. + +## Версии +- До беты у всех компонентов одна версия репозитория. Тег ставится в конце шага: `v0.1.0` — шаг 2, `v0.2.0`…`v0.8.0` — шаги 3–9, `v0.9.x` — бета, `v1.0.0` — коммерческий релиз. +- `CHANGELOG.md` собирается из коммитов (git-cliff) при постановке тега, поэтому формат коммитов важен. +- Протокол агента версионируется отдельно (`protocol_version`). diff --git a/docs/environment.md b/docs/environment.md index 8fc2089..e2e65cd 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -12,6 +12,8 @@ | Node.js | 26.13.0 | `.mise.toml` | Active LTS «Lithium», поддержка до апреля 2029 — самая долгая из доступных | | pnpm | 12.17.0 | `.mise.toml` | Последняя мажорная, выпуску больше 7 дней | | Task | 3.54.0 | `.mise.toml` | Последний стабильный | +| lefthook | 2.2.2 | `.mise.toml` | Git-хуки: формат коммитов, gofmt, gitleaks (`lefthook.yml`) | +| gitleaks | 8.30.1 | `.mise.toml` | Поиск секретов перед коммитом | | Rust | 1.99.1 | `rust-toolchain.toml` | Последний stable; `rustup` ставит его сам при первой сборке в папке проекта | | Tauri | 2.x (CLI 2.12.4) | `package.json` приложений (#2.14) | Стабильная ветка. Tauri 3 пока alpha — не используем | | mise | 2026.10.25 | вручную | Менеджер версий, ставит Go, Node, pnpm, Task по `.mise.toml` | @@ -46,6 +48,7 @@ ``` mise trust mise install + lefthook install ``` 6. **VS Code**: открыть проект и поставить рекомендуемые расширения (`.vscode/extensions.json`). 7. **Перезапустить редактор и терминалы.** @@ -56,7 +59,7 @@ sudo apt install build-essential curl git libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev curl https://sh.rustup.rs -sSf | sh curl https://mise.run | sh # затем подключить: eval "$(~/.local/bin/mise activate bash)" в ~/.bashrc -cd shtil && mise trust && mise install +cd shtil && mise trust && mise install && lefthook install ``` ## Проверка diff --git a/docs/journal/2026-11-08-shared-1.2-git-rules.md b/docs/journal/2026-11-08-shared-1.2-git-rules.md new file mode 100644 index 0000000..9a166da --- /dev/null +++ b/docs/journal/2026-11-08-shared-1.2-git-rules.md @@ -0,0 +1,36 @@ +--- +date: 2026-11-08 +zone: shared +task: "1.2" +items: ["1.2.8", "1.2.9", "1.2.10", "1.13.4"] +branch: feat/1.2-git-rules +pr: — +impact: shared +status: на проверке +author: Frontend +--- + +# [1.2] Правила git, шаблон PR, хуки + +## Сделано +- `docs/contributing.md` — ветки, коммиты по-русски, ежедневный цикл, PR, запреты, версии. +- `.gitea/pull_request_template.md` — описание PR: задача, что сделано, как проверить, чек-лист безопасности и документации. +- `lefthook.yml` + `tools/git-hooks/commit-msg.mjs` — проверка формата коммита, `gofmt` для Go, `gitleaks` для секретов. +- `.mise.toml`: lefthook 2.2.2, gitleaks 8.30.1. +- Настройки Gitea: разрешён только squash, ветки удаляются после слияния (#1.2.7). + +## Решения +- Область в заголовке коммита необязательна, но если указана — только из списка. +- `Refs:` обязателен в каждом коммите (кроме Merge/Revert/fixup). +- prettier подключается в #2.7.2, когда появится pnpm-workspace. + +## Для другой стороны +- После `git pull`: `mise install && lefthook install`. Без `lefthook install` хуки не работают. + +## Проверка +- `commit-msg.mjs`: корректные сообщения проходят; «правки», английский текст, заглавная буква, без `Refs:`, неизвестная область — отклоняются. +- `lefthook run pre-commit` с тестовым токеном в индексе — gitleaks нашёл утечку и остановил коммит. + +## Осталось +- [ ] prettier в pre-commit (#2.7.2). +- [ ] Default merge style в Gitea — «Создать объединённый коммит». diff --git a/docs/status/shared.md b/docs/status/shared.md index a3b7841..541156d 100644 --- a/docs/status/shared.md +++ b/docs/status/shared.md @@ -25,6 +25,7 @@ ## Готово для другой стороны +- 2026-11-08 · frontend → backend · правила git (`docs/contributing.md`), шаблон PR, хуки lefthook: после `git pull` выполнить `mise install && lefthook install` - 2026-11-08 · frontend → backend · версии инструментов зафиксированы: `git pull`, `mise trust && mise install` по `docs/environment.md` ## Запросы между зонами diff --git a/lefthook.yml b/lefthook.yml new file mode 100644 index 0000000..2106511 --- /dev/null +++ b/lefthook.yml @@ -0,0 +1,18 @@ +# Git-хуки проекта. Установка один раз после клонирования: lefthook install +# Правила — docs/contributing.md + +pre-commit: + parallel: true + commands: + gitleaks: + run: gitleaks git --pre-commit --staged --redact --no-banner . + gofmt: + glob: "*.go" + run: gofmt -w {staged_files} + stage_fixed: true + # prettier подключается в #2.7.2 вместе с pnpm-workspace + +commit-msg: + commands: + format: + run: node tools/git-hooks/commit-msg.mjs {1} diff --git a/tools/git-hooks/commit-msg.mjs b/tools/git-hooks/commit-msg.mjs new file mode 100644 index 0000000..73ef166 --- /dev/null +++ b/tools/git-hooks/commit-msg.mjs @@ -0,0 +1,32 @@ +#!/usr/bin/env node +// Проверка сообщения коммита по правилам docs/contributing.md. Вызывается lefthook (commit-msg). +import { readFileSync } from 'node:fs'; + +const TYPES = ['feat', 'fix', 'docs', 'chore', 'refactor', 'test', 'perf', 'build', 'ci', 'style', 'revert']; +const SCOPES = ['server', 'agent', 'helper', 'console', 'ui', 'proto', 'api', 'db', 'ci', 'docs', 'roadmap', 'tools', 'deps']; +const HEADER = new RegExp(`^(${TYPES.join('|')})(\\((${SCOPES.join('|')})\\))?!?: (.+)$`); +const REFS = /^Refs: \d+(\.\d+)+(, ?\d+(\.\d+)+)*$/m; + +const lines = readFileSync(process.argv[2], 'utf8').split(/\r?\n/).filter(l => !l.startsWith('#')); +const msg = lines.join('\n').trim(); +const header = lines[0]?.trim() ?? ''; + +if (/^(Merge|Revert|fixup!|squash!|amend!) /.test(header)) process.exit(0); + +const errors = []; +const m = header.match(HEADER); +if (!m) errors.push(`заголовок должен быть «тип(область): что сделано».\n Типы: ${TYPES.join(', ')}\n Области: ${SCOPES.join(', ')}`); +else { + const desc = m[4]; + if (!/[а-яё]/i.test(desc)) errors.push('описание пишется по-русски'); + if (/^[А-ЯЁ]/.test(desc)) errors.push('описание начинается с маленькой буквы'); + if (/\.$/.test(desc)) errors.push('в конце заголовка не ставится точка'); +} +if ([...header].length > 72) errors.push(`заголовок длиннее 72 символов (${[...header].length})`); +if (lines[1]?.trim()) errors.push('после заголовка нужна пустая строка'); +if (!REFS.test(msg)) errors.push('нет строки «Refs: », например «Refs: 2.11.4» или «Refs: 1.2.8, 1.2.9»'); + +if (errors.length) { + console.error(`\nКоммит отклонён: «${header}»\n${errors.map(e => ' - ' + e).join('\n')}\n\nПример:\n feat(server): добавлен WithTenantTx для доступа к данным организации\n\n Refs: 2.11.4\n\nПравила — docs/contributing.md\n`); + process.exit(1); +}