Как создать идеальный Pull Request

в 6:33, , рубрики: Git, github, gitlab, pull request, Блог компании Voximplant, Программирование, Разработка веб-сайтов, метки:

Как создать идеальный Pull Request - 1С ростом компании меняются люди и проекты. Не так давно в блоге GitHub появилась интересная статья, в которой автор рассказывает, как делать, а как лучше не делать Pull Request’ы. Перевод, традиционно, спрятан под катом.

Правильный подход к написанию Pull Request

  • Четко определите назначение этого pull request. Например:
    Упрощение отображения…
    Исправление обработки…
  • Будет хорошо, если вы включите краткое описание зачем вообще делалась эта работа (включая релевантные ссылки). Не стоит рассчитывать, что читающий реквест разработчик будет знаком со всей историей.
  • Имейте в виду, что этот реквест потенциально может читать любой сотрудник компании. Возможно, через год.
  • Явно пишите, какую реакцию вы ожидаете в ответ на этот реквест. Хотите ли вы от читающего что-то, кроме merge? Просто посмотреть на код, оценить техническую реализацию, критика дизайна, ревью текста и так далее.
  • Явно указывайте когда вы ожидаете ответ. Если реквест в процессе работы, то общепринятой практикой является добавление префикса “[WIP]” (work in progress) к его описанию. Это позволит читающим отгрузить вам ранние комментарии, при этом понимая, что они смотрят не на законченную работу.
  • @Упоминайте тех, кого вы хотели бы видеть в обсуждении реквеста. И упоминайте почему, для этого есть специальный синтаксис:
    /cc @jesseplusplus for clarification on this logic
  • @Упоминать можно не только разработчиков, но и команды. То же относится к причинам, что и зачем вы хотите с ними обсудить:
    /cc @github/security, any concerns with this approach?

Реакция на чужой pull request

  • Постарайтесь изучить контекст, в котором случился этот Pull Request: связанные задачи, обсуждения, история вопроса. Если все это есть, конечно.
  • Если Pull Request вызывает у вас инстинктивную негативную реакцию – возьмите тайм-аут в несколько минут и еще раз все внимательно осмотрите. Возможно, автор не идиот у вас просто случилась ошибка коммуникации. Такое встречается на удивление часто.
  • Спрашивайте, а не предлагайте. Простой и эффективный психологический трюк для облегчения коммуникаций. Фраза «Что ты думаешь насчет использования…?» гораздо меньше провоцирует на конфликт, нежели «убей себя не делай так».
  • Старайтесь объяснять, почему необходимо поменять код (противоречит стилю кодирования? Персональное предпочтение?)
  • Предлагайте пути упростить и улучшить код. Это воспринимается намного лучше, чем просто критика «все плохо».
  • Кстати, о критике. Старайтесь избегать оценок вроде «глупо» по отношению к чужой работе. Очень хорошо помогает наладить коммуникации.
  • Скромнее надо быть. Для дела надо – «не уверен, но давай попробуем…» помогает найти общий язык намного лучше, чем «я 20 лет этим занимаюсь. Делай вот так и не спрашивай почему».
  • Избегайте гипербол («НИКОГДА не делай…»). Все их воспринимают совсем по-разному.
  • Ставьте своей целью развитие профессиональных качеств, знаний компании и увеличения качества продукта. Звучит заезжено? Да, но обычно ставят цель потешить свое самолюбие за счет критики.
  • Учитывайте «negative bias» онлайн коммуникаций (для нейтрального содержания мы всегда предполагаем негативный тон). Чтобы не расставлять по тексту смайлики, можно воспользоваться «позитивным» языком.
  • Если «позитивный» язык использовать трудно (журналисты много лет этому учатся не просто так), то на помощь приходят… эмодзи, как это ни странно. Сравните: ":sparkles: :sparkles: Looks good :+1: :sparkles: :sparkles:” и “Looks good”.

Чужая реакция на ваш pull request

  • По возможности начинайте ответ со слов благодарности, особенно если реакция на ваш реквест противоречива.
  • Если что-то не понятно – не стесняйтесь задавать уточняющие вопросы («I don’t understand, can you clarify?»). Это намного эффективнее, чем пытаться самому «придумать» что имел в виду другой разработчик.
  • Сами старайтесь предоставлять всю уточняющую информацию и рассказывать о причинах тех или иных решений в коде.
  • Старайтесь отвечать на каждый комментарий.
  • Линкуйте коммиты и другие пулл реквесты («Good call! Done in 1682851”)
  • Если обсуждение начало перерастать в дебаты, остановитесь и спросите себя, имеет ли смысл продолжать диалог в письменной форме. Практика показывает, что в большинстве случаев гораздо удобнее обсудить все в скайпе или другом голосовом чате, а затем дописать в виде текста только краткую выжимку и результат обсуждения.

На написание поста меня вдохновил вот этот guide. Я описал приемы, которые мы используем в свой работает и та культура, которой мы стараемся придерживаться. Надеемся, что вы найдете среди них что-нибудь полезное.

Успешных коммуникаций!

Автор: Voximplant

Источник


* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js