Files
shtil/docs/contributing.md
TMSH 800d000ac5 Docs/1.2 private notes (#5)
<!-- Название 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 добавлена в «Ссылки» задачи в дорожной карте

Reviewed-on: #5
Co-authored-by: BrowenSiz <top.timashevsky@gmail.com>
2026-11-09 13:33:30 +00:00

94 lines
7.3 KiB
Markdown
Raw Permalink 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`, ключи. Нашли секрет в истории — сразу сообщить второму, секрет перевыпустить.
## Что не коммитим
Список — в `.gitignore`. Кратко:
- **Секреты:** `.env`, ключи, сертификаты с закрытым ключом, файлы менеджера паролей. Шаблон переменных — только `.env.example` без значений. Пароли стенда — только в менеджере паролей.
- **Личное:** `docs/private/` (заметки с AI), личные настройки AI-инструментов (`.cursor/`, `.windsurf/`, `.claude/`, `*.local.md`), `.mise.local.toml`. Общие правила для AI — только `AGENTS.md` и `docs/ai/`.
- **Данные клиентов и дампы БД:** `*.dump`, `backups/` — там могут быть персональные данные.
- **Прогресс дорожной карты** `roadmap/progress.json` — его хранит roadmap-server в отдельном репозитории.
- **Сборка и зависимости:** `node_modules/`, `target/`, `dist/`, `bin/`, `*.exe`.
Перед коммитом gitleaks проверяет секреты. Если нужный файл попал под `.gitignore` — обсудить, а не добавлять через `git add -f`.
## Версии
- До беты у всех компонентов одна версия репозитория. Тег ставится в конце шага: `v0.1.0` — шаг 2, `v0.2.0`…`v0.8.0` — шаги 3–9, `v0.9.x` — бета, `v1.0.0` — коммерческий релиз.
- `CHANGELOG.md` собирается из коммитов (git-cliff) при постановке тега, поэтому формат коммитов важен.
- Протокол агента версионируется отдельно (`protocol_version`).