[Перевод] Как создать идеальный Pull Request27.04.2016 10:48

Правильный подход к написанию 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. Я описал приемы, которые мы используем в свой работает и та культура, которой мы стараемся придерживаться. Надеемся, что вы найдете среди них что-нибудь полезное.

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

• ↑

  —

  ↓

• 797

• Добавить в избранное 18