Conventional Branch 1.1.0

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

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

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

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

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

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

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

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

Префиксы назначения — описывают намерение работы:

• 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)

Префиксы источника ИИ-агента — идентифицируют ветки, созданные ИИ-агентами кодирования:

Основные ветки (main, master, develop) не используют префикс.

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

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"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
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 Branch в вашем проекте:

• commit-check: Локально проверяет имена веток, сообщения коммитов и связанные метаданные Git.
• commit-check-action: Автоматически проверяет имена веток в GitHub Actions.
• VSCode Conventional Branch: Создаёт имена веток Conventional Branch из Visual Studio Code.
• Conventional Branch Skill: Помогает AI-ассистентам для программирования создавать корректные имена Conventional Branch.

Установите skill командой:

npx skills add conventional-branch/conventional-branch --skill conventional-branch

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

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

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

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

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

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

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

В чём основные различия между v1.1.0 и v1.0.0?

v1.1.0 добавляет Префиксы источника ИИ-агента в качестве основной новой функции (см. следующий вопрос FAQ о том, почему они были введены). Он также включает версионированный веб-сайт с переключателем версий, позволяющим пользователям просматривать спецификации v1.0.0 и v1.1.0. Все существующие имена веток v1.0.0 остаются полностью действительными — без обратно несовместимых изменений.

Зачем добавлять префиксы источника ИИ-агента?

ИИ-агенты кодирования (GitHub Copilot, Cursor, Claude Code, OpenAI Codex и др.) всё чаще используются для генерации кода и создания pull request. Каждый агент использует свой собственный префикс ветки (например, copilot/, cursor/). Стандартизируя эти префиксы в спецификации Conventional Branch, мы обеспечиваем:

1. Быструю идентификацию — рецензенты и инструменты могут немедленно распознать PR, созданные ИИ
2. Проверку инструментами — такие инструменты, как commit-check, могут проверять ветки ИИ-агентов на соответствие спецификации
3. Стандарт регистрации — новые ИИ-агенты могут принять документированный префикс вместо изобретения ситуативных шаблонов

Универсальный префикс ai/ доступен для любого ИИ-агента без выделенного префикса или для команд, которые предпочитают нейтральный по отношению к поставщику идентификатор. Это ключевая новая функция, выпущенная в v1.1.0 — полную сводку изменений между версиями см. в FAQ выше.

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

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

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

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