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

Original author: Keavy
  • Translation
С ростом компании меняются люди и проекты. Не так давно в блоге 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
Облачная платформа голосовой и видеотелефонии

Comments 11

    +2
    «Спрашивайте, а не предлагайте» это правда лучше? Мне всегда казалось, что лучше предложить, если есть что предложить. Спрашивая в ключе «Что ты думаешь насчет использования…?» мы как бы заставляем оппонента оправдываться за какое-то его решение или заставляем доказывать его точку зрения, в любом случае ставим в ситуацию, когда он нам что-то должен.

      0
      Американский стиль делового общения: наиболее мягкие формулировки, похвала, вопросы вместо утверждений, и т.д.

      Было когда-то на Хабре
        +4
        ИМХО, выше шансов, что коммуникация не будет расценена лимбической системой как рычание одного самца на другого, с последующей «естественной» защитной реакцией.
          +1
          Я этот момент воспринял как завуалированное предложение. Что-то вроде «Коллега, а что ты думаешь про использование стандартного функционала нашего фреймворка, вместо своего велосипеда (ссылка на документацию)?». Утрированно конечно.
            0
            Как уже сформулировал выше наш физиолог-любитель, использование вопроса труднее оценить как «наезд». Но возможно, при должном желании. Есть деятели, которые как наезд воспримут любую коммуникацию, даже похвалу. Тут ничего не поделаешь.
            • UFO just landed and posted this here
          +5
          Хорошая этическая статья. Если следовать ей, то вы найдёте своё место в коллективе. Рискну дать совет, что именно должен содержать первый Pull Request. На новом месте работы (мне почему-то представилась именно эта ситуация), Вы — новичок. Умничать не стоит, Вы ещё успеете показать себя в дальнейшем. Найдите места где нарушен codestyle, где нету phpdoc, где IDE что-то подсвечивает и исправьте. Вы типа изучаете код нового проекта и сразу приносите пользу. В первый день работы. И Вы это делаете не потому, что там сидят дураки и не могут это сделать, а потому, что руки не всегда доходят, а вы пришли и сдули пыль тем самым показав, что вы 1) поняли как устроен код 2) ничего не имеете против того, как он устроен (считай уважаете того, кто его написал) 3) вы правильный чувак, который придерживается стандартов кодирования. Вы как бы сразу ставите себя в хорошем свете и в дальнейшем ошибки коммуникации будут случаться реже из-за вашей хорошей репутации в самом начале. Я знаю много людей которые теряются на новом месте работы, не знают чем заняться, или наоборот, устроившись на работу начинают критиковать всё и вся. Может быть моя мысль будет кому-то полезна.
            0
            На рабочем месте руки не доходят, а вот в опенсорсные проекты частенько делаю реквесты с «косметическими» правками. Особенно когда любимая IDE после автоматических инспекций разрисовует скролбар желто-красными красками.
            Но, стоит учитывать еще правила принятые в команде. Они не всегда совпадают с общеринятыми стандартами.
            +1
            Хороший пост. Выжимка которую должен учитывать уважающий себя тимлид. к сожалению самовлюбленные тимлиды — довольно частая история.
              0
              https://github.com/styleguide
              404
                0
                Как быстро все меняется. Поменяли!

              Only users with full accounts can post comments. Log in, please.