#средаразработки

Всем привет! В сообществе техписателей часто звучат разговоры о docs as code и о том, что мы используем методы и инструменты разработчиков. Допустим, мы используем Git. Но задумывались ли вы о том, как именно мы работаем с ветками? Какой тип ветвления нам подходит? Предлагаем вместе обсудить эту важную тему:

Что выбрать: Central Workflow, TBD или GitFlow?

Поясним для новичков: эти три основных подхода к работе с ветками. Конечно, они не включают бессмертного варианта: "Ребята, какая у нас ветка актуальная?" 😉

Итак, коротко:

1️⃣ Central Workflow. Одна ветка основная, рабочая. Все изменения — это коммиты в эту ветку. Удобно, если вы работаете в одиночку в очень маленькой команде разработки и точно знаете, что все изменения в продукте идут последовательно.

👉 Например, один фронтендер создаёт модальные окна, а вы описываете заполнение полей в них и публикуете эти инструкции.

2️⃣ TBD (Trunk-Based Development). Три типа ветки: основная (master или main), feature-ветки и релизная ветка. Одно изменение — одна ветка. Здесь важно: ветка отводится для конкретного изменения, а не для всей функциональности целиком, и сливается в основную ветку как можно быстрее.

👉 Допустим, ваша фича включает изменения в админке и интерфейсе обычного пользователя. Вы описываете изменения в админке и сливаете в основную ветку. Это позволяет вашим коллегам-техписателям или вам же ссылаться на этот участок доки из других статей.

TBD в разработке имеет ещё одну особенность — разработчики могут использовать feature-toggle (флаги), которые включают или выключают какую-то недоработанную часть фичи в базе данных. Поскольку техписатели почти никогда не используют базу данных для сборки документации, нам не нужны флаги, но мы можем закомментировать часть текста.

Когда созданные фрагменты документации часто попадают в основную ветку, feature-ветки создаются уже с этими изменениями, что уменьшает количество конфликтов при последующем слиянии.

Такой подход позволяет обновлять продукт и документацию так часто, как нужно. Например, несколько раз в день.

3️⃣ GitFlow. Большой процесс со всеми типами веток. Классический GitFlow включает ветки main, develop, release-*, hotfix-* и feature-*. В отличие от TBD, в GitFlow каждая feature-ветка — это отдельная полноценная функциональность. Плюс в том, что пока фича не опубликована, ваши черновики по ней в основной ветке не маячат перед глазами других техписов.

👉 Такой подход удобно применять при раннем документировании, когда фича ещё проектируется и реализуется, или когда вы готовите новую структуру документации. Но чем дольше живёт ветка, тем больше будет конфликтов. Поэтому важно подливать в неё изменения из основной ветки, иначе pull-request вырастет до неразрешимых размеров.

Это лишь общее описание подходов, которое умещается в одном посте.

Расскажите, как вы работаете с ветками: придерживаетесь одной методологии или комбинируете их?