Изучаем Git. Урок 24.
Мердж-реквесты и код-ревью
Видеоурок
Конспект урока
Краткое содержание урока, основные инструкции для командной строки, полезные ссылки и советы.
Что такое мердж-реквест?
Зачем нужны мердж-реквесты?
В первую очередь они нужны при работе в команде для проведения код-ревью. Чтобы коллеги увидели новый код и как минимум его просмотрели и оставили замечания или вопросы
Как правильно: merge request или pull request?
Как проходит процедура мердж-реквеста
Немного о markdown
Markdown позволяет форматировать текст: задавать заголовки, списки, цитаты, вставлять ссылки и картинки и даже форматировать код. Насчет кода, возможно, для приграммиста это самая удобная фишка markdown, так как используется достаточно часто
Изучается markdown быстро, разметка очень простая. Вот пример оформления списка, используются звездочки
А вот пример оформления кода, используются апострофы
После этого ваш текст красиво отформатируется, можете попробовать в любом markdown онлайн-редакторе, например, dillinger.io/
Совет от автора
Немного о код ревью
Это отдельная большая тема и git она не касается. Поэтому приведу только кратко причины проводить код ревью
Вопросы на код ревью могут быть совершенно разные и на разные темы. Это всего лишь краткий перечень плюсов от код ревью
Как оповестить коллег о новом мердж-реквесте
Здесь разные варианты, зависит от договоренностей в команде.
Главное договориться как будет удобнее всем в вашей команде
Кто принимает мердж-реквесты
Здесь тоже могут быть разные варианты:
Немного о работе в команде
Gitlab merge request: как сделать и принять MR
Зайдя в Gitlab от имени пользователя, который может работать с проектом скачаем исходный код через git clone
ip адрес в примере используется только для демонстрации, его нужно заменить на свой.
git clone git@ip-address:root/myproject.git
Теперь на локальном компьютере присутствуют скрипты проекта, или один скрипт index.py как в примере.
Переходим в каталог
Теперь можно создать новую ветку
В ней вносим изменения
Открыв файл в текстовом редакторе добавим комментарий
Затем добавляем все содержимое каталога на staging
И заливаем в ветку update-code
После обновления страницы в интерфейсе Gitlab будет отображаться вторая ветка
Рядом с именем ветки есть кнопка Merge request
При нажатии на нее открывается диалог позволяющий задать описание, добавить комментарий, установить Milestone и выбрать кому из разработчиков будет отправлен MR.
Также можно установить, что нужно чье-либо одобрение для принятия Merge-request и слияния с веткой master.
После заполнения полей формы нужно нажать «Submit merge request» внизу.
Теперь тот кому отправлен MR получит оповещение и сможет увидеть все внесенные изменения, затем закрыть MR, выполнить слияние с master или начать дискуссию.
Нажатие на первую позволит увидеть разницу до и после внесения изменений, код будет выводиться на экране разделенном на две части вертикально. Аналогично git diff.
Если выбрать «Check out branch» — отобразится инструкция с командами, позволяющими скачать изменений на локальный компьютер, исправить все конфликты и загрузить в репозиторий.
В случае если изменения корректны и не нанесут ущерба проекту можно нажать Merge.
В консоли когда merge выполнен, можно переключиться на master и забрать через pull изменения.
Изменения будут залиты в master. Найдя MR всегда можно воспользоваться опцией revert для отмены.
GitLab Work in branches
Этот документ объясняет механизм ветвления и то, каким образом публиковать свои изменения в GitLab.
Терминология
master: главная ветвь проекта. Обычно ветки создаются от master. Вы не должны делать свою работу напрямую в master и должны создавать новые ветки для каждой задачи над которой вы работаете самостоятельно или сообща. Когда работа закончена выполняется слияние вашей ветки обратно в master. Ветвление и слияние в Git должно стать частью вашего ежедневного рабочего процесса.
origin: основной удалённый репозиторий в котором вы публикуете свои изменения и из которого получаете изменения других разработчиков.
Ветки
Две основные долгоживущие ветки:
Настройка GitLab аккаунта
GitLab должен знать что вам разрешено делать, а что нет. Для этого вам нужно настроить доступ по SSH-ключам. Это описано здесь
Цикл разработки
Мы используем подход, основанный на мерж-реквестах. Багфиксы и доработки должны быть опубликованы в собственной ветке разработчика, которая создаётся специально под задачу.
Затем создаётся запрос на слияние новой ветки с веткой master в основном репозитории. Следует избегать публикации непосредственно в ветку master.
Правила именования коммитов
Комментарии к правкам следует писать по-русски в кодировке UTF-8.
Многострочный комментарий состоит из однострочного заголовка отделённого от тела пустой строкой.
Длина строки заголовка и тела не должна превышать 80 символов.
Тело комментария должно содержать информацию о том что сделано и зачем это было сделано.
Многострочный комментарий используется при необходимости детализировать назначение набора изменений.
Если правка относится к задаче в трекере, в заголовке указывается номер задачи Jira.
IS-1276. Экспорт РПП в формат CSV. Выгрузка НДС в назначении платежа.
Правила именования веток
Имена функциональных веток должны кратко, в 1-2-3-4 слова (слова разделяются дефисом), характеризовать назначение ветки.
Нет необходимости включать в наименование ничего не значащие или понятные только вам аббревиатуры, постфиксы, указания на нежелаемое поведение.
Хороший пример: fix-service-control
Создание merge request
Идём на GitLab, находим модуль, в котором мы опубликовали свою ветку, далее на закладке Merge requests и нажимаем кнопку Create merge request.
Вводим Title. Заголовок обязательно должен включать номер задачи в Jira и тему, характеризующую изменения.
В Description можем указывать какие именно изменения были сделаны, почему предпочтение отдано именно такому подходу.
Дополнительно здесь можно указать информацию, которая может быть полезна ревьюверу чтобы сориенироваться в предлагаемых правках.
А также упомянуть тех, кому эти изменения могут быть интересны (чьё мнение вам важно). Для этого введите /cc @
Здесь работает markdown-синтаксис.
Проверяем что в список Changes попали только коммиты с вашей ветки.
Выбираем того, кому предстоит принимать ваш запрос из выпадающего списка Assignee.
Ставим галку Remove source branch when merge request is accepted.
Жмём Submit merge request. Мерж-реквест создан. О дальнейшей его судьбе вы будете узнавать из уведомлений, которые начнут приходить на электронную почту.
Больше мерж-реквестов
Для набора изменений, затронувшего несколько модулей, если изменения в этом модуле не совсем тривиальны и нуждаются в ревью (см. ниже раздел «Когда направлять мерж-реквест, а когда нет»), создаётся по одному мерж-реквесту на каждый модуль.
Имена веток во всех модулях должны совпадать. Для навигации между ними в описании добавляются перекрёстные ссылки.
Кто принимает мерж-реквест
Мерж-реквест должен быть одобрен хотя бы одним разработчиком, который не принимал непосредственного участия в написании кода этого изменения
Ревьюверу следует обращать внимание на:
Комментарии и замечания должны находиться непосредственно в данном мерж-реквесте.
Исправления замечаний делаются в той же ветке и видны в мерж-реквесте.
Getting started with merge requests
A merge request (MR) is the basis of GitLab as a code collaboration and version control.
When working in a Git-based platform, you can use branching strategies to collaborate on code.
A repository is composed by its default branch, which contains the major version of the codebase, from which you create minor branches, also called feature branches, to propose changes to the codebase without introducing them directly into the major version of the codebase.
Branching is especially important when collaborating with others, avoiding changes to be pushed directly to the default branch without prior reviews, tests, and approvals.
When you create a new feature branch, change the files, and push it to GitLab, you have the option to create a merge request, which is essentially a request to merge one branch into another.
The branch you added your changes into is called source branch while the branch you request to merge your changes into is called target branch.
The target branch can be the default or any other branch, depending on the branching strategies you choose.
In a merge request, beyond visualizing the differences between the original content and your proposed changes, you can execute a significant number of tasks before concluding your work and merging the merge request.
You can watch our GitLab Flow video for a quick overview of working with merge requests.
How to create a merge request
Learn the various ways to create a merge request.
What you can do with merge requests
Assignee
Choose an assignee to designate someone as the person responsible for the first review of the merge request. Open the drop down box to search for the user you wish to assign, and the merge request is added to their assigned merge request list.
Multiple assignees
Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it.
Similarly, assignees are removed by deselecting them from the same dropdown menu.
Reviewer
The merge request Reviewers feature enables you to request a review of your work, and see the status of the review. Reviewers help distinguish the roles of the users involved in the merge request. In comparison to an Assignee, who is directly responsible for creating or merging a merge request, a Reviewer is a team member who may only be involved in one aspect of the merge request, such as a peer review.
To request a review of a merge request, expand the Reviewers select box in the right-hand sidebar. Search for the users you want to request a review from. When selected, GitLab creates a to-do list item for each reviewer.
Merge requests to close issues
If the issue is confidential, you may want to use a different workflow for merge requests for confidential issues to prevent confidential information from being exposed.
Deleting the source branch
When creating a merge request, select the Delete source branch when merge request accepted option, and the source branch is deleted when the merge request is merged. To make this option enabled by default for all new merge requests, enable it in the project’s settings.
This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. It is only visible to users with the Maintainer role in the source project.
If the user viewing the merge request does not have the correct permissions to delete the source branch and the source branch is set for deletion, the merge request widget displays the Deletes source branch text.
Branch retargeting on merge
The feature today works only on merge. Clicking the Remove source branch button after the merge request was merged will not automatically retarget a merge request. This improvement is tracked as a follow-up.
merge request guide
Руководство по мерж-реквесту (Merge Request Guide)
Страницы в этом разделе содержат рекомендации для разработчиков, которые готовят мерж-реквест и проходящих проверку кода. Эти рекомендации должны помочь вам готовить запросы на изменения и быстрее проходить ревью и получать более качественные результаты.
Термины
Написание хороших описаний MR
Будущие разработчики будут искать ваш MR на основе его описания. Если вся важная информация содержится в коде, а не в описании, им будет намного сложнее найти ваш MR.
Заголовок
Первая строка
Первая строка описания MR должна быть краткой сводкой конкретно того, что делается MR, за которой следует пустая строка. Это то, что в большинстве случаев при поиске увидят в первую очередь, поэтому эта первая строка должна быть достаточно информативной, чтобы им не приходилось читать ваш MR или его полное описание, чтобы получить общее представление. Идея о том, что на самом деле сделал ваш MR.
Постарайтесь, чтобы ваша первая строка была короткой, целенаправленной и точной. Ясность и полезность для читателя должны быть главной заботой. По традиции, первая строка описания MR представляет собой законченное предложение, написанное как императивное предложение. Например, скажите «Удалите RPC FizzBuzz и замените его новой системой» («Delete the FizzBuzz RPC and replace it with the new system.”) вместо «Удаление RPC FizzBuzz и замена его новой системой» («Deleting the FizzBuzz RPC and replacing it with the new system.”). Тем не менее, вам не нужно писать остальную часть описания как императивные предложения.
Тело информативно
Данная часть описания должна быть информативной. Сюда может входить краткое описание решаемой проблемы и почему это лучший подход. Если есть какие-либо недостатки в подходе, их следует упомянуть. При необходимости включите справочную информацию, такую как номера заданий, результаты тестов и ссылки на проектные документы.
Если вы включаете ссылки на внешние ресурсы, учтите, что они могут быть невидимы для будущих читателей из-за ограничений доступа или политик хранения. Где возможно, включите достаточно контекста для рецензентов и будущих читателей, чтобы понять MR.
Даже маленькие MR заслуживают небольшого внимания к деталям. Поместите MR в контекст.
Плохие описания MR
Некоторые из них являются реальными описаниями MR. Их авторы могут полагать, что они предоставляют полезную информацию, но они не служат цели описания MR.
Просмотрите описание перед отправкой MR
MR могут претерпеть значительные изменения в режиме просмотра. Целесообразно просмотреть описание MR в режиме предварительного обзора перед отправкой MR, чтобы убедиться, что описание все еще отражает то, что делает MR.
Не все системы обладают режимом обзора. В таком случае после отправки лучше просмотреть MR и поправить при необходимости.
Маленькие MR
Зачем готовить маленькие MR?
Маленькие, простые MR:
Обратите внимание, что рецензенты могут отклонить ваши изменения по единственной причине его слишком большого размера. Для того, чтобы разделить изменения на несколько MRs после того, как вы их уже написали, может потребоваться много работы. Или потребуется много времени, чтобы убедить рецензента принять ваше большое изменение. Изначально проще просто написать маленькие MR.
Что такое маленький MR?
Имейте в виду, что, хотя вы были тесно связаны с вашим кодом с момента, когда вы начали его писать, рецензент часто не имеет контекста. То, что кажется вам приемлемым размером MR, может быть ошеломляющим для вашего рецензента. Если вы сомневаетесь, напишите MR, которые меньше, чем вы думаете, что вам нужно написать. Рецензенты редко жалуются на получение слишком маленьких MR.
Когда большие MR допуcтимы?
Есть несколько ситуаций, в которых большие изменения не так плохи:
Разделение по файлам
Например: вы отправляете один MR для изменений в буфер протокола и другой MR для изменений в коде, который использует этот протокол. Вы должны представить протокольный MR перед кодом MR, но оба они могут быть рассмотрены одновременно. Если вы сделаете это, вы можете сообщить обоим наборам рецензентов о других написанных вами MR, чтобы у них был контекст для ваших изменений.
Отдельные рефакторинги
Обычно лучше проводить рефакторинг в отдельном MR из изменений функций или исправлений ошибок. Например, перемещение и переименование класса должны быть в другом MR, чем исправление ошибки в этом классе. Рецензентам намного легче понять изменения, вносимые каждым MR, когда они разделены.
Однако небольшие изменения, такие как исправление имени локальной переменной, могут быть включены в MR изменения функции или исправления ошибки. Разработчики и рецензенты должны решить, когда рефакторинг настолько велик, что это сделает проверку более сложной, если она будет включена в ваш текущий MR.
Храните связанный тестовый код в том же MR
Избегайте разделения тестового кода на отдельный MR. Тесты, проверяющие изменения вашего кода, должны идти в один и тот же MR, даже если это увеличивает количество строк кода.
Тем не менее, независимые тестовые модификации могут сначала войти в отдельные MR, аналогично рекомендациям по рефакторингу. Это включает:
Не ломай сборку
Если у вас есть несколько MR, которые зависят друг от друга, вам нужно найти способ убедиться, что вся система продолжает работать после отправки каждого MR. В противном случае вы можете прервать сборку для всех ваших коллег-разработчиков на несколько минут между вашими представлениями MR (или даже дольше, если что-то пойдет не так неожиданно с вашими последующими представлениями MR).
Не можете сделать MR достаточно маленьким
Иногда вы сталкиваетесь с ситуациями, когда кажется, что ваш MR должен быть большим. Это очень редко правда. Авторы, которые практикуют написание небольших MR, почти всегда могут найти способ разделить функциональность на серию небольших изменений.
Прежде чем создать большой MR, подумайте, может ли предшествующий ему MR с рефакторингом проложить путь к более чистой реализации. Поговорите со своими товарищами по команде и посмотрите, есть ли у кого-нибудь мысли о том, как реализовать функциональность в небольших MR.
Если все эти варианты не работают (что должно быть крайне редко), тогда заранее получите согласие ваших рецензентов на просмотр большого MR, чтобы они были предупреждены о предстоящем. В этой ситуации ожидайте, что вы пройдете через процесс проверки в течение длительного времени, будьте бдительны, чтобы не допустить ошибок, и будьте особенно внимательны при написании тестов.
Как обрабатывать комментарии рецензента
Когда вы отправили MR на рецензию, вполне вероятно, что ваш рецензент ответит несколькими комментариями на ваш MR. Вот несколько полезных вещей, которые нужно знать об обработке комментариев рецензента.
Не принимай это на свой счет
Целью обзора является поддержание качества кодовой базы и программных продуктов. Когда рецензент дает критику вашего кода, думайте о нем, как о своей попытке помочь вам, базе кодов и сообществу, а не как о личной атаке на вас или ваши способности.
Иногда рецензенты чувствуют разочарование и выражают это разочарование в своих комментариях. Это не очень хорошая практика для рецензентов, но как разработчик вы должны быть к этому готовы. Спросите себя: «Какова конструктивная вещь, которую рецензент пытается донести до меня?» а затем действовать так, как будто это то, что они на самом деле сказали.
Никогда не отвечайте в гневе на комментарии к коду. Это серьезное нарушение профессионального этикета, которое навсегда останется в инструменте проверки кода. Если вы слишком сердиты или раздражены, чтобы отвечать доброжелательно, отойдите на некоторое время от компьютера или поработайте над чем-нибудь еще, пока не почувствуете себя достаточно спокойно, чтобы ответить вежливо.
В общем, если рецензент не дает обратной связи конструктивным и вежливым образом, объясните это лично. Если вы не можете поговорить с ними лично или по видео-звонку, отправьте им личное письмо. Объясните им, что вам не нравится, и что вы хотели бы, чтобы они делали по-другому. Если они также неконструктивно отреагируют на это частное обсуждение или не принесут ожидаемого эффекта, то обратитесь к своему менеджеру в случае необходимости.
Исправить код
Если рецензент говорит, что он не понимает что-то в вашем коде, первым вашим ответом должно быть разъяснение самого кода. Если код не может быть разъяснен, добавьте комментарий к коду, объясняющий, почему код существует. Если комментарий кажется бессмысленным, только тогда ваш ответ должен быть объяснением в инструменте проверки кода.
Если рецензент не понимает какой-то фрагмент вашего кода, вероятно, другие читатели этого кода тоже не поймут. Написание ответа в инструменте обзора кода не поможет будущим читателям кода, но разъяснение вашего кода или добавление комментариев к коду поможет им.
Думай сам
Написание MR может занять много работы. Часто очень приятно наконец отправить его на рассмотрение, почувствовать, что оно сделано, и быть уверенным, что никакой дальнейшей работы не требуется. Поэтому, когда рецензент возвращается с комментариями о том, что может быть улучшено, легко рефлекторно думать, что комментарии неправильные, рецензент блокирует вас без необходимости, или они должны просто позволить вам отправить MR. Тем не менее, независимо от того, насколько вы уверены в этом, сделайте шаг назад и подумайте, предоставляет ли рецензент ценную обратную связь, которая поможет кодовой базе и сообществу. Ваш первый вопрос к себе всегда должен быть: «Прав ли рецензент?»
Если вы не можете ответить на этот вопрос, вероятно, рецензент должен уточнить свои комментарии.
Если вы обдумали это и по-прежнему считаете себя правым, не стесняйтесь ответить объяснением того, почему ваш метод действий лучше для кодовой базы, пользователей и / или сообщества. Часто рецензенты действительно предлагают предложения и хотят, чтобы вы сами думали о том, что лучше. Возможно, вы на самом деле знаете что-то о пользователях, базе кода или MR, чего не знает рецензент. Так что заполните их; дайте им больше контекста. Обычно вы можете прийти к какому-то согласию между вами и рецензентом, основываясь на технических фактах.
Разрешение конфликтов
Ваш первый шаг в разрешении конфликтов всегда должен заключаться в том, чтобы попытаться прийти к согласию с вашим рецензентом. Если вы не можете достичь консенсуса, см. Стандарт код-ревью, в котором приведены принципы, которым необходимо следовать в такой ситуации.
