## Варианты именования веток :tanabata_tree:
Рассмотрев несколько распространенных практик именования веток (см. [источники](#Рассмотренные-источники) в конце документа), я пришёл к варианту, который кажется наиболее подходящим для нас.
Ознакомьтесь, пожалуйста, с ним и дайте обратную связь.
#### Предлагаемый вариант
Пусть имена веток имеют следующий формат:
```text
<номер-заявки>-<краткое-пояснение>
```
Здесь:
* `<номер-заявки>` – полный идентификатор заявки в JIRA, например, `UPCSEC-9541`
* `<краткое-пояснение>` – компактная фраза с описанием происходящего в ветке. Рекомендуемый формат фразы:
> <действие>-<егоОбъект>-<место>
Важно, чтобы действие было выражено глаголом и стояло на первом месте – тогда имена будут единообразными, а понимать их будет проще.
Простые примеры полностью подходящих названий:
```text
UPCSEC-1234-fix-test-in-trinity
UCPSEC-3495-refactor-limits-in-limon
UPCSEC-4955-replace-validation-in-shared
UPCSEC-9321-set-constraints-for-batman
UPCSEC-9889-update-spring-boot-for-all
UPCSEC-9541-change-version-of-fsg-starter
UPCSEC-8739-add-docs-and-tests-to-asimov
UPCSEC-9149-apply-code-review-to-bacardi
UPCSEC-0000-rewrite-everything-in-pushkin
```
Но как быть, если тех самых “мест” несколько? Спецификация ссылочных имён в git [допускает](https://git-scm.com/docs/git-check-ref-format) использование запятых, но на практике оказалось, что это может вызывать проблемы, например, со сборками в Jenkins - плагин [Extended Choice Parameter Plugin](https://github.com/jenkinsci/extended-choice-parameter-plugin) не умеет экранировать запятые, из-за чего некорректно интерпретирует имена таких веток. Поэтому в качестве разделителя лучше использовать всё тот же дефис:
```text
UPCSEC-7895-bump-version-of-pcpoints-redis-cam-starter
UPCSEC-9103-fix-headers-for-filo-trinity-genotype-client
UPCSEC-9999-make-sbp2.0-in-houston-limon-trinity
```
Как видно, точки тоже допустимы, **но** не в начале и не в конце имени ветки.
#### Преимущества
Такой формат именования веток кажется удачным потому, что он:
* простой: не требует запоминать много правил и исключений;
* гибкий: под него подпадает большинство повседневных случаев;
* обратно-совместимый: многие ветки названы примерно так уже сейчас, поэтому временный разлад не должен оказаться большим;
* “искабельный”: он мотивирует включать в себя то, по чему потом вероятнее всего будет делаться поиск;
* читабельный: глагол в начале пояснения и название компонента в его конце позволяют быстро выцеплять взглядом самую суть.
#### Ответы на распространённые вопросы вида “А почему не …?”
##### Почему не группировать ветки по типу задачи? (bug/feature/etc но не `release`)
Потому что:
1. Это заставляет лишний раз думать, а думать в нашей работе страшно.
1. Не всегда на вопрос “какого типа эта задача?” есть однозначный ответ.
1. Эта информация избыточна на фоне того, что в имени ветки есть ID заявки, в которой тип задачи описан куда подробнее.
1. Мы не пользуемся практиками, в которых такая классификация была бы полезной.
###### Почему не "`/`" между номером заявки и пояснением?
Потому что:
1. Этот символ подразумевает логическую группировку нескольких элементов под одним общим свойством, но мы весьма редко создаём несколько веток под одну задачу, поэтому такая группировка избыточна.
1. При использовании имени ветки в составе URI (как например, в сборках в Jenkins), этот символ придётся экранировать, что снижает читабельность адресов и может порождать баги (если экранирование не сделать).
1. Есть стороннее [мнение](https://stackoverflow.com/questions/273695/what-are-some-examples-of-commonly-used-practices-for-naming-git-branches#comment22993711_6065944), что активное использование этого символа может мешать работе CI.
1. Проще писать имя ветки, когда все разделители одинаковые.
##### Почему не “`_`” между частями имени?
Потому что:
1. В идентификаторе заявки подчерки использовать нельзя, а смешивать два вида разделителей не удобно: приходится лишний раз думать, когда нажимать Shift, а когда нет; это порождает неприятные опечатки.
1. Git корнями растёт из Linux, а там части длинного имени принято разделять дефисами. Этот опыт кажется весомым.
##### Почему не “1234” вместо “UPCSEC-1234”, ведь мы же только над одним проектом JIRA работаем?
Потому что:
1. Тогда сломается навигация по именам заявок в продуктах Atlassian (где она хоть как-то работала раньше);
1. Тогда сломается навигация по именам заявок в IDEA (там можно настроить автоматическое превращение подстрок вида UPCSEC-\**** в ссылки на заявки JIRA)
1. Тогда ухудшится автодополнение в git клиенте (CLI): увидев несколько цифр после команды checkout и получив команду TAB, он не поймёт, что имелось в виду: то ли имя ветки, то ли SHA-1 хэш коммита.
### Приложения
#### Текущие разновидности имён
* `feature/UPCSEC-1234-houston-sbp-check`
* `feature/UPCSEC-1234-sbp-check`
* `houston/UPCSEC-1234-sbp-check`
* `all/UPCSEC-1234-sbp-check`
* `UPCSEC-1234-sbp-check`
#### Рассмотренные источники
* [Git - git-check-ref-format Documentation](https://git-scm.com/docs/git-check-ref-format)
* [SO: What are some examples of commonly used practices for naming git branches?](https://stackoverflow.com/questions/273695/what-are-some-examples-of-commonly-used-practices-for-naming-git-branches)
* [Git Branching Naming Convention: Best Practices – {coding}Sight](https://codingsight.com/git-branching-naming-convention-best-practices/)
* [Git branch naming conventions - DeepSource](https://deepsource.io/blog/git-branch-naming-conventions/)