Conventional Branch

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, chore/upgrade-node-v20.11).
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.
• Conventional Branch Skill: Помогает AI-ассистентам для программирования создавать корректные имена Conventional Branch.

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

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

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

Что такое имя ветки?

Имя ветки — это метка, которую Git присваивает линии разработки, например main или feature/add-login-page; Git хранит его как ссылку (ref) в refs/heads/. Git принимает самые разные имена, поэтому само по себе имя ветки ничего надёжного о работе в ней не сообщает. Conventional Branch задаёт ему структуру <тип>/<описание>: тип, который говорит, для чего предназначена работа, а затем короткое описание строчными буквами, слова в котором разделены дефисами. Например:

• feature/add-login-page
• bugfix/fix-header-bug
• release/v1.2.0

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

Как следует называть ветку feature?

Начните её с feature/ или с короткого псевдонима feat/ и опишите функциональность после косой черты. Если для работы есть тикет в вашем инструменте управления проектами, включите его номер. Например:

• feature/add-login-page
• feat/add-login-page
• feature/issue-123-new-login

Что такое ветка chore?

Ветка chore/ предназначена для задач, не связанных с кодом, таких как обновление зависимостей или документации. Типов веток намеренно меньше, чем типов Conventional Commits (см. ниже), поэтому такие работы по сопровождению относятся к chore/. Например:

• chore/update-dependencies
• chore/upgrade-node-v20.11
• chore/update-generated-files

Некоторые боты для обновления зависимостей, например Renovate, тоже можно настроить на этот префикс; см. Боты и автоматизация.

Как следует называть ветку release?

Используйте release/, а после него укажите то, что готовит ветка, обычно номер версии. Точки допускаются, но не в начале или в конце описания и не рядом с дефисом:

• release/v1.2.0 — допустимо
• release/v1.2.0. — недопустимо: точка в конце
• release/v1.-2.0 — недопустимо: дефис рядом с точкой

Единый префикс также позволяет конвейеру реагировать на release/*, например для автоматического развёртывания из веток релиза.

Как следует называть ветку hotfix?

Используйте hotfix/ для срочного исправления и bugfix/ (или fix/) для несрочного. Опишите, что исправляется, и включите номер тикета, если он есть. Например:

• hotfix/security-patch
• hotfix/issue-123-security-patch
• bugfix/fix-header-bug — для несрочного исправления

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

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

Conventional Branch придумал эти префиксы?

Нет. Такие префиксы, как feature/, hotfix/ и release/, распространились около 2010 года благодаря инструменту git-flow и используются по умолчанию в таких инструментах, как модель ветвления Bitbucket. Conventional Branch опирается на эту практику, а не заменяет её. Он добавляет точное определение, общее для людей и инструментов: фиксированный набор типов, формальную грамматику, регулярное выражение для проверки, опубликованное в spec.json, и тестовые случаи соответствия, чтобы любой валидатор принимал ровно одни и те же имена.

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

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

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

Да, как расширение на уровне команды. Типы из грамматики — это те, которые принимает любой соответствующий спецификации инструмент, поэтому ветка вида unknown/some-task недопустима по самой спецификации. Если команде нужны дополнительные типы (например, experiment/), их следует явно указать в валидаторе (например, в allow_branch_types в commit-check) и задокументировать, чтобы участники команды и автоматизированные инструменты действовали согласованно. Например, репозиторий самой спецификации добавляет в свою конфигурацию commit-check тип dependabot/ для веток, которые создаёт Dependabot.

Почему имена веток должны быть в нижнем регистре?

По двум причинам. Во-первых, Git обычно хранит ссылки на ветки как файлы в .git/refs/heads/, а файловые системы macOS и Windows по умолчанию не различают регистр: Feature/login и feature/login там указывают на один и тот же путь, а в Linux это две разные ветки. Поэтому репозиторий, допускающий оба варианта, может вести себя по-разному в разных клонах. Во-вторых, одно написание проще набирать, искать и сопоставлять: инструменту, который срабатывает на release/*, не нужно учитывать ещё и Release/*.

В чём основные различия между 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.