Files
shtil/docs/contributing.md
T
TMSHandDevin 3b0c846cf6 chore: добавлены правила git, шаблон PR и проверочные хуки
Правила работы с ветками, коммитами и 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>
2026-11-08 18:34:20 +03:00

84 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Как мы работаем с 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`).