Как писать отличные пулл-реквесты

Original author: Keavy McMinn
  • Translation
С ростом компании, люди и проекты меняются. Для продолжения развития культуры, которую мы хотим иметь в GitHub, мы сочли полезным напомнить самим себе цели, которые преследуем в коммуникациях. Мы недавно представили эти гайдлайны, чтобы помочь самим себе быть лучше, когда мы взаимодействуем через пулл-реквесты.

Подход к написанию пулл-реквестов


  • Опишите цель данного пулл-реквеста. Например:
    Это заглушка для…
    Это упрощает отображение…
    Это исправляет обращение к…
  • Подумайте о предоставлении краткой информации о том, почему эта работа имела место быть (с соответствующими ссылками); не предполагайте, что все знакомы с историей.
  • Помните, что каждый в компании может прочитать этот пулл-реквест, поэтому содержание и тон могут проинформировать людей отличных от тех, кто принимает обсуждение, сейчас или в будущем.
  • Будьте конкретны в том, какую обратную связь вы хотите получить, например: пару незамыленных глаз, обсуждение технического подхода, критика дизайна, ревью копии.
  • Будьте конкретны в том, когда вы хотите получить обратную связь. Если пулл-реквест находится в работе, то так и сообщите об этом. Префикс “[WIP]” в заголовке — простой и понятный путь для сообщения статуса.
  • @упоминайте людей, которых вы хотите подключить к беседе, указывайте почему. (“/cc @jesseplusplus для пояснения этой логики”)
  • @упоминайте команды, которые вы хотите вовлечь в дискуссию, указывайте почему. (“/cc github/security, какие-нибудь опасения при таком подходе?”)


Оставляя обратную связь


  • Ознакомьтесь с контекстом проблемы и причинами, почему этот пулл-реквест существует.
  • Если вы сильно несогласны, отвлекитесь на пару минут, прежде чем ответить. Думайте, прежде чем говорить.
  • Спрашивайте, а не утверждайте. (“Что ты думаешь о том, чтобы попробовать…?”, вместо “Не делай так…”)
  • Объясните свои причины, почему вы думаете, что код должен быть изменен. (Не в соответствии со стилевым гайдом? Личное предпочтение?)
  • Предлагайте пути упрощения или улучшения кода.
  • Избегайте использования унизительных слов, таких, как “глупый”, когда ссылаетесь на работу, которую кто-то проделал.
  • Будьте скромны. (“Я не уверен, давай попробуем…”)
  • Избегайте использование гипербол. (“НИКОГДА не делай…”)
  • Стремитесь развить профессиональные навыки, общие знания и качество продукта, посредством групповой критики.
  • Не забывайте про негативный оттенок при онлайн-общении. (Если содержание нейтрально, то мы предполагаем, что тон задан негативный). Можете ли вы использовать более позитивный язык, вместо нейтрального?
  • Используйте emoji для пояснения тона. Сравните “image image Выглядит неплохо image image image” и “Выглядит неплохо.”


Отвечая на фидбек


  • Рассмотрите возможность начать с выражения благодарности. Особенно, если фидбек получился неоднозначным.
  • Просите уточнить. (“Я не понимаю, не могли бы вы уточнить?”)
  • Уточняйте, поясняйте решения, которые вы принимали, чтобы прийти к решению вопроса.
  • Пытайтесь ответить на каждый комментарий.
  • Ссылайтесь на все соответствующие коммиты или пулл-реквесты. (“Отличное решение! Реализовано в 1682851”)
  • Если есть растущее непонимание или обсуждение, спросите себя, лучшим ли способом продолжения общения будет текст. Поговорите (виртуально) лицом к лицу, затем совместно обдумайте опубликование итогов для резюмирования оффлайн-обсуждений (удобно для тех, кто будет пытаться понять, сейчас или в будущем).

Эти гайдлайны частично были вдохновлены код-ревью гайдом Thoughtbot.

Наши гайдлайны подходят к тому, как мы работаем, и к культуре, которую мы хотим развивать. Надеемся, что вы тоже найдёте их полезными.

Приятного общения!

———
Все исправления ошибок и улучшения перевода можно отправлять через image пулл-реквесты. Не забывайте пользоваться этим гайдом при оформлении пулл-реквеста ;)

Similar posts

AdBlock has stolen the banner, but banners are not teeth — they will be back

More
Ads

Comments 10

    +29
    Выглядит неплохо!
      +20
      Используйте emoji для пояснения тона.

      Это серьезно?
        +10
        Это не шутки, мы встретились в маршрутке
        Да, так написано в оригинале image
          +3
          В США люди на этом подвинуты. По сравнению с нами по крайней мере.
            0
            Если в США люди на этом подвинуты, то что же тогда творится в Японии? Массовая истерия?
          +12
          Да, такой себе социально-культурный сдвиг. У американцев улыбка, кивок, большой палец вверх — это норма, они так выражают обычный, нормальный ход вещей, а вот если тебе не улыбнулись и не похлопали по плечу, то это уже воспринимается чуть ли не как проявление агрессии. У нас норма — это «каменное лицо», улыбка предназначается только близким друзьям и родственникам, а агрессия — ну это когда уже бьют морду. Поэтому мы кажемся такими «грустными и неприветливыми» американцам, а они — такими «фальшиво улыбчивыми и не к месту позитивными» нам.
          +69
          imageimageНикогда так не делай!imageimage
            +15
            На самом деле поднята очень важная тема. Я видел много хороших и важных пулл-реквестов, которые не принимались в крупные open source проекты из-за плохого или вообще отсутствующего описания. Потому что никто, кроме автора не знает, что это и зачем. У команд, разрабатывающих крупные проекты (фреймворки, например) нет кучи времени, чтобы раскуривать ваш код в попытках разобраться, зачем же вы его написали. И пулл реквесты лежат и тухнут.

            В качестве примера посмотрите вот этот PR: rails/rails#13435 — невнятное описание про то, что «ограничение не имеет смысла» сильно затормозило пулл реквест и только после более десятка комментариев от сообщества с +1 и более подробным описанием что не так в текущей ситуации и что это баг и он дико бесит обратили внимание разработчиков и сдвинули дело с мёртвой точки. (Сейчас это исправлено и попало в релиз).

            Поэтому, если вы решили отправить патч в какой-либо проект (это уже превосходно само по себе!), пожалуйста, напишите к нему сопроводительное описание и расскажите в нём, что за проблему реального мира вы решаете, почему она не решается без этого патча и насколько лучше будет с ним. Особенно если вы русский разработчик и решаете проблемы, которых в остальном мире не существует, пример такого обсуждения: savonrb/savon#566
              +1
              Отличные советы. Более того, я думаю, что большинство из них было бы полезно применять и в повседневной жизни. Let's make the world better.
                +2
                Такое впечатление, что код пишут, чтобы потеребить друг другу самолюбие, а не решить какую-то задачу. Я к тому, что при обсуждении какого-либо кода я, блин, код обсуждал, а не следил за «тоном» собеседников, и не переживал, что кому-то невыносимо больно от отсутствия эмотиконов.

                Я периодически почитывал блог этих Thoughtbot. В последнее время начало казаться, что кодингом они занимаются минимум времени, а вместо этого пишут гайды про то как «Сбросить свой ментальный кэш» ( >_< ).

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