Git давно перестал быть инструментом только для исходного кода. В подходе «документация как код» (docs-as-code) аналитик хранит спецификации, модели, глоссарии и шаблоны в Git-репозитории — с полной историей изменений, рецензированием через pull request и возможностью автоматической сборки. Заметка объясняет, зачем Git системному аналитику, как устроен базовый рабочий процесс и где границы этого подхода по сравнению с формальным управлением требованиями.
1. Суть темы
Docs-as-code — хранение аналитических артефактов в текстовых форматах (Markdown, YAML, PlantUML) в Git-репозитории рядом с кодом или в отдельном репозитории документации. Для аналитика Git даёт:
Единый источник истины — команда работает с одной актуальной версией требований.
Историю изменений — видно, кто, когда и зачем изменил формулировку; можно откатиться к предыдущей версии.
Параллельную работу — несколько аналитиков дорабатывают разные разделы без риска затереть чужие правки.
Git — один из режимов работы с требованиями, типичный для Agile-команд и продуктов с docs-as-code. Он не заменяет специализированные RM-инструменты (Jama, DOORS) и формальный change control через CCB в регулируемых или contract-heavy контекстах — см. 02.05.06 Инструменты управления требованиями (Jama, DOORS, Confluence) и 02.05.02 Управление изменениями (Change Control Board). Сравнение подходов и выбор инструмента — там же; здесь — техническая модель работы с Git.
Когда Git для документации — неполный или плохой выбор:
бизнес-стейкхолдеры работают только в Confluence/Wiki без доступа к репозиторию;
обязателен Word/PDF с электронной подписью как единственный юридически значимый артефакт;
RM-система — system of record по статусам, baseline и аудиту, а Git — лишь черновик.
В таких случаях Git может быть рабочей копией, а «официальная» публикация — через экспорт или dual publishing (Git как источник, Confluence/Wiki как витрина для бизнеса). Автоматическая сборка сайта, проверка орфографии и публикация версий документации завязаны на CI/CD — см. 07.06 CICD и конвейеры — влияние на требования; в этой заметке — только связка «репозиторий → PR → merge».
2. Ключевые понятия
Термин
Описание простыми словами
Репозиторий (repository)
Хранилище всех файлов проекта и их истории; локальное и удалённое (GitHub, GitLab, Bitbucket).
Коммит (commit)
Снимок состояния файлов с сообщением и уникальным хешем (SHA).
Ветка (branch)
Независимая линия разработки; изоляция работы над задачей.
Клонирование (clone)
Копирование удалённого репозитория на локальную машину (git clone).
Индекс (staging area)
Промежуточная область перед коммитом (git add).
Слияние (merge)
Объединение изменений из одной ветки в другую.
Pull request (PR)
Запрос на включение изменений; в GitLab — merge request; основной механизм рецензирования.
Конфликт (conflict)
Два автора изменили один фрагмент; требуется ручное разрешение.
Protected branch
Политика на main: запрет прямого push, обязательные approvers, иногда CODEOWNERS — без этого «утверждённая main» — лишь декларация намерений.
CODEOWNERS
Файл в репозитории: автоматически назначает обязательных рецензентов по пути (/specs/ — аналитики, /openapi/ — архитектор и SA).
Базовая модель ветвления в статье — Feature Branch: рабочая ветка на задачу, слияние в main через PR. Для релизов с hotfix/release-ветками смотрите Git Flow — расширение той же идеи, описанное в источниках ниже; для большинства doc-репозиториев достаточно feature branch.
3. Как применяется в работе аналитика
Типовой workflow
gitGraph
commit id: "Исходная версия SRS"
branch feature/user-profile-req
checkout feature/user-profile-req
commit id: "Добавлены требования к профилю"
commit id: "Исправлены замечания рецензента"
checkout main
merge feature/user-profile-req tag: "docs-v2.1"
branch feature/order-report
checkout feature/order-report
commit id: "Описание отчёта по заказам"
commit id: "Добавлены макеты и НФТ"
checkout main
merge feature/order-report tag: "docs-v2.2"
Клонировать репозиторий — один раз в начале работы.
Создать ветку под задачу (требование, user story):
git checkout -b feature/order-cancellation
Именование: feature/краткое-описание, bugfix/описание, docs/описание. Внешние участники без прав на основной репозиторий работают через fork и PR из своего форка; команда внутри репо — через branch.
Ответить на замечания — новые коммиты в той же ветке обновляют PR.
После merge в main изменение попадает в стабильную ветку — если настроены protected branch, минимум approvers и (при необходимости) связь с процессом согласования. Merge в mainсам по себе не равен юридически принятому baseline в waterfall или регуляторике — см. 05.01 Waterfall и V-model.
PR связывают с задачей в Jira/YouTrack через ID в commit message или automation (smart commits); это облегчает навигацию, но не заменяет статус требования в RM — см. 02.05.05 Жизненный цикл требования.
Ветвление и рецензирование
main — стабильная версия документации после прохождения PR.
feature/<название> — изолированная доработка; после merge ветку удаляют.
PR даёт прозрачность diff, обсуждение построчно и историю решений в комментариях. Разрешение конфликтов в Markdown обычно простое. Правило one sentence per line (каждое предложение с новой строки) снижает конфликты: Git сравнивает построчно, review и git blame показывают точную строку, а не абзац целиком. При инцидентах («кто изменил формулировку NFR в прошлом релизе») git log и git blame по файлу спецификации помогают восстановить автора, дату и контекст коммита — это дополнение к статусам в RM, а не замена 02.05.05 Жизненный цикл требования.
Стратегия merge (squash, merge commit, rebase) влияет на audit trail — договоритесь в команде заранее. Squash упрощает историю main, но уничтожает промежуточные коммиты — в том числе «исправлены замечания рецензента». В споре «кто когда согласовал формулировку» остаётся только PR в UI хостинга, а не полная цепочка SHA. Merge commit сохраняет все шаги ветки; для регулируемых и аудируемых контекстов это часто предпочтительнее. В любом случае комментарии PR — отдельный след согласования.
Monorepo и отдельный doc-repo
Ситуация
Куда класть спецификации
Зачем
Один сервис, OpenAPI меняется вместе с кодом
Monorepo: /specs, /openapi рядом с исходниками
Один PR на «контракт + реализация»; review видит связку
Несколько команд, общая база знаний, редкие релизы docs
Отдельный doc-repo
Независимые PR и теги docs-v2.x без шума от code PR
Регуляторный audit только по документам
Doc-repo с собственными protected branch и CODEOWNERS
Изолированный audit trail
В monorepo CODEOWNERS по путям разделяет зоны ответственности: изменения в /specs/ требуют approve аналитиков, в /openapi/ — SA и архитектора. Релизные теги могут быть общими (v2.1.0) или раздельными (app-v2.1.0 + docs-v2.1) — зафиксируйте правило в README репозитория.
Состав репозитория
/docs /specs # SRS, Use Cases — см. [[04.01 Форматы документов (Vision&Scope, BRD, SRS, FRD)]] /models # UML, BPMN, ER — исходники и экспорт PNG/SVG /glossary # см. [[10.01.14 Шаблон глоссария и словаря данных]], [[03.03.03 Словарь данных (описание)]] /templates # [[10.01.01 Шаблон User Story]], [[10.01.13 Шаблон архитектурного решения (ADR)]] … /adr # ADR по [[10.01.13 Шаблон архитектурного решения (ADR)]] /openapi # контракты — см. [[03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)]] /presentations README.md CODEOWNERS # обязательные approvers по каталогам .gitignore
Что удобно reviewить в PR: Markdown, Mermaid в .md, .puml, OpenAPI/YAML. Для .drawio XML-diff в PR часто нечитаем — многие команды коммитят исходник вместе с PNG/SVG или только экспорт; выберите политику и зафиксируйте в CONTRIBUTING. Бинарные DOCX, PDF, Visio — в Git только при необходимости; иначе храните в RM/SharePoint и оставляйте ссылку в Markdown. Крупные изображения — Git LFS или внешнее хранилище.
Версионирование документов и откат ошибок
Тег docs-v2.3 фиксирует снимок документации на момент релиза. Для SA это практический инструмент: git checkout docs-v2.1 -- specs/orders/ — посмотреть SRS, актуальную для релиза 2.1; git diff docs-v2.1 docs-v2.2 -- specs/ — что изменилось между baseline документов. Связь «версия specs ↔ версия продукта/API» согласуйте явно — см. 03.05.07 Управление версионированием API и жизненным циклом; не полагайтесь на совпадение номеров по умолчанию. Дополнительно поле версии в шапке SRS помогает читателям вне Git.
Если в main попала неверная SRS после merge:
git revert <merge-commit> — безопасный откат с сохранением истории; предпочтителен для shared main.
Hotfix-ветка (bugfix/wrong-srs-section) — срочное исправление через тот же PR-процесс.
git cherry-pick — перенести отдельные правки из hotfix в другую ветку релиза.
Force push в protected main запрещён — это норма, а не препятствие; revert и hotfix закрывают типовой сценарий «опубликовали не то».
Практики и инструменты
Сообщения коммитов: Conventional Commits (feat(srs): …) удобны для release notes; в чисто doc-репозитории команда может упростить правило до «ID задачи + суть изменения».
Атомарные коммиты — одно логическое изменение; не смешивать опечатки с новым функциональным блоком.
Синхронизация с main — регулярно подтягивайте изменения в feature-ветку.
Инструменты: GitHub, GitLab, Bitbucket; GUI — GitHub Desktop, Sourcetree, GitKraken; VS Code с Git и плагинами для Markdown/PlantUML/Mermaid. Obsidian Git удобен для личной или team PKM-базы, но не заменяет review через shared repo и PR в корпоративном процессе. Сборка сайта — MkDocs, Docusaurus, Hugo; pipeline — 07.06 CICD и конвейеры — влияние на требования, контекст DevOps — 05.04 DevOps и непрерывная поставка — влияние на анализ.
4. Типовые ошибки и ограничения
Ошибка
Последствие
Что делать
Считать merge в main формальным утверждением без политики
«Утверждённые» требования без audit trail
Protected branch, approvers, CODEOWNERS; при необходимости CCB — 02.05.02 Управление изменениями (Change Control Board); baseline в waterfall — 05.01 Waterfall и V-model
Полагаться только на ID в commit message для трассировки
Коммит ≠ статус требования; версия документа ≠ версия продукта