Несколько лет назад GitHub представил шаблоны запросов на вытягивание, чтобы упростить процесс разработки программного обеспечения в команде. Это файлы, которые позволяют разработчикам написать описание запроса на вытягивание с заранее определенной структурой, которая поможет их товарищам по команде лучше понять, что они сделали.
Они очень полезны, потому что помогают контекстуализировать процесс проверки кода. В конце концов, это очень трудоемкий процесс для разработчиков и очень сложный для нетехнических заинтересованных сторон, которые высказывают более целостное мнение о коде, который потенциально может быть объединен в рабочую среду.
Отсутствие описания пулл-реквеста очень болезненно, представьте себе: вы готовите сложное, но изысканное блюдо с друзьями. Один из ваших друзей, уверенный в своих кулинарных способностях, протягивает вам кастрюлю с кипящей смесью. Он утверждает, что это секретный ингредиент блюда. Вы пробуете это, и вы остаетесь в недоумении. Вы спрашиваете его о рецепте и получаете ужасное сообщение «Я не могу дать вам рецепт». Вы видите кучу ингредиентов, без этикеток или объяснений, и вы теряетесь.
Это то же разочарование, которое испытывает разработчик, когда видит сообщение "Нет описания" в запросе на вытягивание.
Шаблоны запросов на вытягивание решают эту проблему, заставляя разработчиков контекстуализировать процесс проверки кода. Однако наличие слишком сложного шаблона запроса на извлечение снизит скорость разработки.
Пример распаковки стандартного шаблона запроса на слияние
Каков идеальный пример шаблона запроса на включение? Давайте рассмотрим два примера и сведем их к нескольким фундаментальным принципам.
Это пример канонического шаблона запроса на включение (укороченная версия того, что есть на нашем репо). На наш взгляд, это минимальный порог информации, который должен содержать описание пулл-реквеста.
<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. --> ## Type of change <!-- Please delete options that are not relevant or write your own. --> - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update - [ ] Chore: cleanup/renaming, etc - [ ] RFC
Несмотря на то, что этот пример запроса на вытягивание заставляет автора написать описание и установить флажок, указывающий, какой тип изменения это предлагаемое изменение вставляет в кодовую базу, мы могли бы сделать намного лучше.
Давайте рассмотрим идею добавления дополнительной информации в шаблон запроса на вытягивание.
Скрытые издержки сложности
Богатый контекстом, но очень сложный пример шаблона запроса на вытягивание негативно влияет на продуктивность команды.
В этом последнем примере шаблона запроса на вытягивание мы добавили много шагов, и все они здесь по очень веской причине.
## Summary <!-- Provide a concise summary "Why are the changes needed"? Include any relevant links, such as Jira tickets, Slack discussions, or design documents. --> ## Changes Made <!-- Describe the specific changes that have been made in this pull request. Provide details on the approach taken to address the problem and any notable implementation details. --> ## Type of change <!-- Please delete options that are not relevant or write your own. --> - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update - [ ] Chore: cleanup/renaming, etc - [ ] RFC ## Checklist - [ ] I have added comments to code in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] Any dependent changes have been merged and published in downstream modules <!-- Optional Sections --> <details> <summary><strong>Expand for optional sections</strong></summary> ## Screenshots <!-- If the changes are visual, including screenshots or GIFs can help reviewers understand them more easily. --> ## Related issues <!-- A link to any related issues or bugs that the pull request addresses, connecting the code's context with the problem it solves. --> ## Testing instructions <!-- Instructions on how to test the changes made in the pull request, helping reviewers validate the code. --> ## Special notes for your reviewer <!-- If there are any specific instructions or considerations you want to highlight for the reviewer, include them in this section. --> </details> <!-- End of Optional Sections -->
Однако этот пример шаблона запроса на вытягивание сложен. Заполнение каждого раздела отнимет у ваших разработчиков драгоценное время.
Выступает за минимализм
Лучший шаблон — самый простой. Самый простой, который не пропускает важную информацию.
Есть ли способ получить объем контекста из второго примера шаблона запроса на вытягивание с временными затратами первого примера шаблона запроса на вытягивание?
Переход от сложности к простоте
Вернемся к последнему примеру шаблона запроса на извлечение. Каждый отдельный элемент находится на своем месте по очень веской причине, но разработчикам в вашей команде потребуется очень много времени, чтобы делать это каждый раз, когда они отправляют запрос на вытягивание.
Скриншоты могут показаться очень тривиальной вещью. Но в большинстве случаев вам на самом деле нужно видео (возможно, переименование этого раздела — возможность улучшить такой пример шаблона запроса на вытягивание). Видео, показывающее потоки приложения, затронутые запросом на вытягивание. Это включает в себя не только переключение контекста, но и настройку записи экрана таким образом, чтобы автор запроса на включение объяснил, что было изменено. Вы также в конечном итоге связываетесь с Figma.
Инструкции по тестированию также могут быть недооценены. «Я напишу одно или два предложения, и этого будет достаточно, чтобы проинструктировать рецензента». Это больше, чем это. Какой пограничный случай нужно протестировать? Есть ли он на первом месте? Как вы можете выполнить неочевидный шаг в процессе? Есть ли определенное имя пользователя, с которым вам нужно попробовать это? А размеры экрана? Если у вас хорошо налажен процесс TDD, никто не посмеет (и не должен) объединять запрос на включение без ручного тестирования.
Раздел связанных вопросов очень интересен. Из новых разделов, представленных в этом примере шаблона запроса на вытягивание, этот самый полезный. Это крупнейший поставщик контекста. Он дает информацию о предыдущих подходах, которые были как успешными, так и неудачными, что представляет ценность для пользователя, а что нет, и как исторически влияла бизнес-логика. Эта информация может жить не только в пулл-реквестах, но и в цепочках сообщений Slack, в тикетах управления проектами в таких системах, как Jira и Linear; а также в системах документации, таких как Notion и Confluence. Чаще всего вы либо перезваниваете в Zoom (что далеко не идеально, это больше всего снижает скорость разработки), либо ссылаетесь на часть документации или обсуждение.
Наше приложение GitHub может помочь вашей команде автоматизировать поиск этих связанных фрагментов информации.
Заключение
Шаблоны запросов на вытягивание необходимы, но если вы их чрезмерно усложните, вы снизите скорость разработки вашей команды. Держите его как можно проще. Мы предлагаем использовать первый пример шаблона запроса на вытягивание или пример шаблона запроса на вытягивание от Watermelon и дополнить такие запросы на вытягивание нашим приложением GitHub.
Первоначально опубликовано на https://www.watermelontools.com.
