## Варианты именования веток :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/)