Conventional Branch 1.0.0

Краткое изложение

Conventional Branch относится к структурированной и стандартизированной конвенции именования веток Git, которая направлена на то, чтобы сделать ветки более читаемыми и действенными. Мы предложили некоторые префиксы веток, которые вы можете использовать, но вы также можете указать свою собственную конвенцию именования. Последовательная конвенция именования упрощает идентификацию веток по типу.

Ключевые моменты

1. Имена веток, ориентированные на цель: Каждое имя ветки четко указывает на её цель, что позволяет всем разработчикам легко понять, для чего предназначена ветка.
2. Интеграция с CI/CD: Использование согласованных имён веток может помочь автоматизированным системам (таким как конвейеры непрерывной интеграции/непрерывного развёртывания) запускать определённые действия на основе типа ветки (например, автоматическое развёртывание из веток релиза).
3. Командная работа: Это способствует сотрудничеству внутри команд, делая цель ветки явной, уменьшая недопонимание и облегчая членам команды переключение между задачами без путаницы.

Спецификация

Префиксы именования веток

Спецификация веток поддерживает следующие префиксы и должна быть структурирована как:

<тип>/<описание>

• main: Основная ветка разработки (например, main, master или develop)
• feature/ (или feat/): Для новых функций (например, feature/add-login-page, feat/add-login-page)
• bugfix/ (или fix/): Для исправления ошибок (например, bugfix/fix-header-bug, fix/header-bug)
• hotfix/: Для срочных исправлений (например, hotfix/security-patch)
• release/: Для веток, подготавливающих релиз (например, release/v1.2.0)
• chore/: Для задач, не связанных с кодом, таких как зависимости, обновления документации (например, chore/update-dependencies)

Основные правила

1. Используйте строчные буквенно-цифровые символы, дефисы и точки: Всегда используйте строчные буквы (a-z), цифры (0-9) и дефисы (-) для разделения слов. Избегайте специальных символов, подчёркиваний или пробелов. Для веток релиза точки (.) могут использоваться в описании для представления номеров версий (например, release/v1.2.0).
2. Никаких последовательных, начальных или конечных дефисов или точек: Убедитесь, что дефисы и точки не появляются последовательно (например, feature/new--login, release/v1.-2.0), а также в начале или в конце описания (например, feature/-new-login, release/v1.2.0.).
3. Сохраняйте ясность и краткость: Имя ветки должно быть описательным, но кратким, чётко указывающим цель работы.
4. Включайте номера тикетов: При необходимости включайте номер тикета из вашего инструмента управления проектами для упрощения отслеживания. Например, для тикета issue-123 имя ветки может быть feature/issue-123-new-login.

Формальная грамматика

Следующая грамматика ABNF (Augmented Backus-Naur Form) формально определяет допустимые имена веток:

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; строчные буквы a-z
DIGIT           = %x30-39   ; цифры 0-9

Примечание: Последовательные дефисы или точки, а также дефисы или точки в начале или конце описания не допускаются.

Примеры

Заключение

• Ясная коммуникация: Одно только имя ветки обеспечивает чёткое понимание её цели и изменения кода.
• Дружественность к автоматизации: Легко интегрируется в процессы автоматизации (например, различные рабочие процессы для feature, release и т. д.).
• Масштабируемость: Хорошо работает в больших командах, где множество разработчиков одновременно работают над различными задачами.

В заключение, conventional branch разработан для улучшения организации проекта, коммуникации и автоматизации в рабочих процессах Git.

Часто задаваемые вопросы

Почему типы веток не так детализированы, как Conventional Commits (например, build, ci, docs, style, refactor)?

Ветки отличаются от коммитов — они временные и используются в основном до слияния. Введение слишком большого количества типов веток было бы лишним и усложняло бы их управление и запоминание.

Какие инструменты можно использовать для автоматического определения того, что член команды не соответствует данной спецификации?

Вы можете использовать commit-check для проверки спецификации веток или commit-check-action, если ваш код размещён на GitHub.

Могу ли я определить собственные типы веток помимо перечисленных?

Да. Спецификация определяет рекомендуемый набор типов, но команды могут определять дополнительные пользовательские типы для своего рабочего процесса. Однако важно чётко документировать пользовательские типы, чтобы все члены команды и автоматизированные инструменты были осведомлены о них.

Как Conventional Branch соотносится с Conventional Commits?

Conventional Branch вдохновлён Conventional Commits и следует схожей философии: привнести структуру, читаемую людьми и машинами, в метаданные Git. Conventional Commits стандартизирует сообщения коммитов, а Conventional Branch стандартизирует имена веток. Обе спецификации естественным образом дополняют друг друга.

Как следует обращаться с долгоживущими ветками, такими как develop или staging?

Долгоживущие интеграционные или средовые ветки (например, develop, staging, production) рассматриваются как основные ветки и не требуют префикса. В формальной грамматике ABNF к trunk‑веткам относятся только main/master/develop; использование дополнительных долгоживущих веток (таких как staging, production и т.п.) как trunk‑веток является командным расширением за пределами базовой спецификации и должно быть явно задокументировано. Их следует именовать последовательно во всём проекте.