Files
shtil/docs/contributing.md
T
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

7.3 KiB
Raw Blame History

Как мы работаем с 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).