5 шагов к созданию крутого пул-реквеста

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

Поэтому действительно важно создать крутой пул-реквест, который поможет лучше понять ваш код на ревью и сделать все необходимые выводы. Далее расписаны пять шагов, следуя которым, вы с большей вероятностью добьетесь успеха.

1. Ветвление

Ветвление означает, что вы отклоняетесь от основной линии разработки и продолжаете работу, не связываясь с ней.

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

Новая ветка должна быть создана из последнего кода ее восходящей ветки. Иначе говоря, HEAD коммит локальной ветки должен совпадать с HEAD коммитом восходящей. 

Это поможет сделать историю коммитов более ясной в будущем пул-реквесте. Ветвление с помощью команд Git можно сделать следующим образом:

git fetch --all #1 git checkout upstream/dev #2 git checkout -b Feature/New #3

• #1 Запросить последнюю версию кода из вашего удаленного репозитория. 
• #2 Переключиться на последний код восходящей ветки разработки.
• #3 Создать новую ветку под именем Feature/New, используя последний код ветки разработки.

Вы также можете применить указанный способ для получения того же результата, используя SourceTree. Что касается стандартных имен ветвей, то в большинстве случаев можно найти master, release или development. А какие имена лучше подойдут для ветвей, посвященных рефакторингу, добавлению новых элементов или исправлению багов? Я бы предложил два варианта имени.

На основе номера тикета или проблемы

Предположим, что вы работаете над Jira тикетом VAJ-96 об устранении бага на главном экране. В этом случае вы можете назвать ветку так:

VAJ-96/Fix_Bug_In_Home_Screen

Этот принцип подойдет и для тикетов, требующих создания нескольких веток: 

VAJ-96/Fix_Bug_1_In_Home_Screen VAJ-96/Fix_Bug_2_In_Home_Screen VAJ-96/Fix_Bug_3_In_Home_Screen Имена по типу ветки

В разработке существует по меньшей мере три типа веток, которые вы можете использовать в работе, включая рефакторинг, исправление и добавление элементов. Основываясь на этом, мы можем разбить ветки по категориям так:

Feature/Pet_Dating Feature/Music_For_Pet#or Fix/Loading_Issue Fix/Crash_In_Home_Screen#or Refactor/Duplicated_Code Refactor/Module_A

Если вы пользуетесь терминалом, то одним из преимуществ станет функция автодополнения. В случае с SourceTree она выглядит так:

Можно легко разбить ветку по категориям согласно упомянутому выше принципу.

2. Коммит

Крутой пул-реквест должен иметь крутой список коммитов. Что ж, разберёмся с коммитами.

Содержимое коммита

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

Не оттягивайте с коммитом до полного завершения, но и не стоит частить, делая коммит после каждой строчки кода, главное  —  делать его вовремя.

Имя коммита

Доводилось ли вам видеть коммиты: “это коммит”, “что исправить” или “я не знаю, что я делаю”? Звучит смешно, но встречается каждый день. Честно говоря, иногда вы или ваши коллеги можете ужаснуться, когда нужно найти что-то из предыдущих версий. Поэтому имя коммита должно передавать конкретные изменения и выглядеть, например, так:

Fix: - Fixed the crash in Home Screen. Feature: - Implemented GameView in Play Screen. Merge: - Merged latest develop to the feature branch. Chore: - Increased the build number to 68 on Production. Refactor: - Replaced Singleton pattern by Dependencies Injection.

Старайтесь делать сообщение коротким, но ясным. 

Ваш пул-реквест не станет крутым, если код не будет чист и без ошибок. Поэтому очень важно уделить внимание чистоте, структуризации, оптимизации и соблюдению всех условий написания кода.

Я советую поставить себя на место просматривающего код человека в будущем и в самом конце еще раз посмотреть на код перед созданием пул-реквеста (шаг 3). Если вы сочтете, что в нем есть потенциальные улучшения, то обязательно улучшайте. Пусть код выглядит наилучшим образом. В будущем это сохранит много времени вам и вашим коллегам.

3. Предложение пул-реквеста

Хороший пул-реквест должен иметь четкое имя, сопровождающееся детальным описанием, и дополнительными тегами или аннотациями.

Имя

В имени должны быть отражены сами изменения, поясняющие общую идею пул-реквеста. При этом можно также использовать принцип именования, который мы рассмотрели в начале статьи.

Описание

Описание помогает лучше понять, зачем что-то написали в коде, его достоинства и ознакомиться с пояснениями его создателя. Иначе говоря, оно должно отвечать на три вопроса: 

• Зачем? Над какими тикетами, проблемами или предложениями вы работаете?
• Что? Что именно вы сделали?
• Как? Что нужно знать тем, кто смотрит ваш код?

Теги и аннотации

По желанию вы можете добавить больше информации в пул-реквест, чтобы облегчить его обзор.

4. Обзор

Крутой пул-реквест активно обсуждается его создателями и всеми, кто просматривает код. Люди могут не сообщать своего мнения о коде до его одобрения. Когда они все же это делают, важно правильно понять их комментарии до внесения каких бы то ни было изменений. В такие моменты возникают конфликты: разные люди могут использовать разные подходы в решении задач.

Если вы считаете, что ваш вариант кода верный и является лучшим решением, то имейте уважение к просматривающим код людям и давайте свои пояснения спокойно. Если же вы осознаете, что в коде действительно есть проблемы, то не откладывайте внесение изменений и делайте следующий коммит уже с их учетом, это абсолютно нормально. 

С другой стороны, будучи обозревателем кода, лучше сосредотачиваться именно на коде, а не на человеке.

Не тратьте много времени на споры и не переходите на личности. В конце концов, все мы одна команда, которая старается сделать мир лучше.

5. Одобрение и слияние

Разрешив все вопросы о внесении изменений и получив одобрение, вы можете сливать ваши пул-реквесты с удаленной веткой. Для этого существует множество способов. Я использую два основных: добавление коммита на слияние поверх всех остальных коммитов пул-реквеста или сжатие всех коммитов в один на слияние.

Первый способ в основном применяется при слиянии крупного элемента или переработанной ветки с удаленной веткой для сохранения истории коммитов. 

Второй способ не учитывает историю коммитов в пул-реквесте. Он сжимает все существующие коммиты и создает один единственный, упрощая и очищая историю. В связи с этим он чаще применяется для мелких элементов и быстро устраняющих баг веток. 

Слияние завершено? Вы сами решаете, что делать с созданной вами моделью ветвления. Вы можете либо стереть ее, либо сохранить для дальнейшей работы. 

Поздравляю с завершением задачи! Сделайте небольшой перерыв и приступайте к следующей. 

Благодарю вас за внимание!

---

Перевод статьи Xuan-Gieng Nguyen: How To Create a Great Pull Request in Just 5 Steps.