chore: добавлены правила git, шаблон PR и проверочные хуки (#4)

Правила работы с ветками, коммитами и 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>
Reviewed-on: #4
Co-authored-by: BrowenSiz <top.timashevsky@gmail.com>
This commit was merged in pull request #4.
This commit is contained in:
TMSHandDevin authored and TMSH committed 2026-11-08 15:35:13 +00:00
1 parent 377a7f3807
commit dcee1faf7d
9 files changed
+202 -1

No files matched your search

+25
View File
@@ -0,0 +1,25 @@
<!-- Название PR: «[ID] Что сделано», по-русски. Например: [2.11] Изоляция организаций -->
**Задача:** #<!-- ID задачи в дорожной карте -->
**Пункты:** <!-- 2.11.4, 2.11.6 -->
## Что сделано
-
## Как проверить
1.
## Скриншоты
<!-- Для изменений интерфейса. Иначе удалить раздел. -->
## Чек-лист
- [ ] Коммиты и название PR по-русски, в каждом коммите есть `Refs:`
- [ ] Ветка свежая: `git rebase origin/main`, конфликтов нет
- [ ] Запросы к данным организации — с `tenant_id` и через `WithTenantTx`
- [ ] Права проверяются на сервере (`access.Require` / `ScopesFor`), интерфейс только скрывает
- [ ] Новая функция — за флагом из каталога функций
- [ ] Миграции только новые, смерженные не изменены; контракты (`api/`, `proto/`, `migrations/`) — отдельным PR
- [ ] Тесты добавлены или обновлены; для новой таблицы организации — тест изоляции
- [ ] Секретов и персональных данных в коде, логах и документах нет
- [ ] Документация обновлена: запись журнала, `docs/status/`, ADR при значимом решении
- [ ] Ссылка на этот PR добавлена в «Ссылки» задачи в дорожной карте
+2
View File
@@ -4,3 +4,5 @@ go = "1.27.3"
node = "26.13.0" node = "26.13.0"
pnpm = "12.17.0" pnpm = "12.17.0"
task = "3.54.0" task = "3.54.0"
lefthook = "2.2.2"
gitleaks = "8.30.1"
+1
View File
@@ -122,6 +122,7 @@ shtil-roadmap.html дорожная карта
- Хорошо: `feat(server): добавлен WithTenantTx для доступа к данным организации`, `fix(console): исправлен повтор запроса после истечения токена`. - Хорошо: `feat(server): добавлен WithTenantTx для доступа к данным организации`, `fix(console): исправлен повтор запроса после истечения токена`.
- Плохо: `fix`, `правки`, `update files`, `WIP`, английский текст. - Плохо: `fix`, `правки`, `update files`, `WIP`, английский текст.
- Заголовок squash-коммита при слиянии PR тоже по-русски, обычно совпадает с названием PR. - Заголовок squash-коммита при слиянии PR тоже по-русски, обычно совпадает с названием PR.
- Формат проверяет хук `commit-msg` (lefthook), `--no-verify` не используется. Полные правила git — `docs/contributing.md`, описание PR — по шаблону `.gitea/pull_request_template.md`.
- Изменения `api/openapi.yaml`, `proto/`, `migrations/` — отдельным PR. - Изменения `api/openapi.yaml`, `proto/`, `migrations/` — отдельным PR.
- Значимое техническое решение — ADR в `docs/adr/NNNN-название.md` и поле «Решение» в дорожной карте. - Значимое техническое решение — ADR в `docs/adr/NNNN-название.md` и поле «Решение» в дорожной карте.
- Без лишних комментариев: комментарий объясняет «почему», а не «что». - Без лишних комментариев: комментарий объясняет «почему», а не «что».
+83
View File
@@ -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/<ID>-кратко` | `feat/2.13-design-tokens` |
| Исправление | `fix/<ID>-кратко` | `fix/2.14-token-refresh` |
| Документы | `docs/<ID>-кратко` | `docs/1.11-information-architecture` |
| Служебное | `chore/<ID>-кратко` | `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`).
+4 -1
View File
@@ -12,6 +12,8 @@
| Node.js | 26.13.0 | `.mise.toml` | Active LTS «Lithium», поддержка до апреля 2029 — самая долгая из доступных | | Node.js | 26.13.0 | `.mise.toml` | Active LTS «Lithium», поддержка до апреля 2029 — самая долгая из доступных |
| pnpm | 12.17.0 | `.mise.toml` | Последняя мажорная, выпуску больше 7 дней | | pnpm | 12.17.0 | `.mise.toml` | Последняя мажорная, выпуску больше 7 дней |
| Task | 3.54.0 | `.mise.toml` | Последний стабильный | | 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` ставит его сам при первой сборке в папке проекта | | Rust | 1.99.1 | `rust-toolchain.toml` | Последний stable; `rustup` ставит его сам при первой сборке в папке проекта |
| Tauri | 2.x (CLI 2.12.4) | `package.json` приложений (#2.14) | Стабильная ветка. Tauri 3 пока alpha — не используем | | Tauri | 2.x (CLI 2.12.4) | `package.json` приложений (#2.14) | Стабильная ветка. Tauri 3 пока alpha — не используем |
| mise | 2026.10.25 | вручную | Менеджер версий, ставит Go, Node, pnpm, Task по `.mise.toml` | | mise | 2026.10.25 | вручную | Менеджер версий, ставит Go, Node, pnpm, Task по `.mise.toml` |
@@ -46,6 +48,7 @@
``` ```
mise trust mise trust
mise install mise install
lefthook install
``` ```
6. **VS Code**: открыть проект и поставить рекомендуемые расширения (`.vscode/extensions.json`). 6. **VS Code**: открыть проект и поставить рекомендуемые расширения (`.vscode/extensions.json`).
7. **Перезапустить редактор и терминалы.** 7. **Перезапустить редактор и терминалы.**
@@ -56,7 +59,7 @@
sudo apt install build-essential curl git libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev 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://sh.rustup.rs -sSf | sh
curl https://mise.run | sh # затем подключить: eval "$(~/.local/bin/mise activate bash)" в ~/.bashrc 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
``` ```
## Проверка ## Проверка
@@ -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 — «Создать объединённый коммит».
+1
View File
@@ -25,6 +25,7 @@
## Готово для другой стороны ## Готово для другой стороны
<!-- Формат: - YYYY-MM-DD · зона → зона · что готово · где (путь, эндпоинт, ADR) --> <!-- Формат: - YYYY-MM-DD · зона → зона · что готово · где (путь, эндпоинт, ADR) -->
- 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` - 2026-11-08 · frontend → backend · версии инструментов зафиксированы: `git pull`, `mise trust && mise install` по `docs/environment.md`
## Запросы между зонами ## Запросы между зонами
+18
View File
@@ -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}
+32
View File
@@ -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: <ID пункта>», например «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);
}