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

С ростом компании меняются люди и проекты. Не так давно в блоге 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

Источник