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

Автор: admin от 22-01-2015, 10:47, посмотрело: 579

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


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



  • Опишите цель данного пулл-реквеста. Например:
    Это заглушка для…
    Это улучшает отображение…
    Это исправляет обращение к…

  • Подумайте о предоставлении краткой информации о том, почему эта работа имела место быть (с соответствующими ссылками); не предполагайте, что все знакомы с историей.

  • Помните, что каждый в компании может прочитать этот пулл-реквест, поэтому содержание и тон могут проинформировать людей отличных от тех, кто принимает обсуждение, сейчас или в будущем.

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

  • Будьте конкретны в том, когда вы хотите получить обратную связь. Если пулл-реквест находится в работе, то так и сообщите об этом. Префикс “[WIP]” в заголовке — простой и понятный путь для сообщения статуса.

  • @упоминайте людей, которых вы хотите подключить к беседе, указывайте почему. (“/cc @jesseplusplus для пояснения этой логики”)

  • @упоминайте команды, которые вы хотите вовлечь в дискуссию, указывайте почему. (“/cc @github/security, какие-нибудь опасения при таком подходе?”)



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



  • Ознакомьтесь с контекстом проблемы и причинами, почему этот пулл-реквест существует.

  • Если вы сильно несогласны, отвлекитесь на пару минут, прежде чем ответить. Думайте, прежде чем говорить.

  • Спрашивайте, а не утверждайте. (“Что ты думаешь о том, чтобы попробовать…?”, вместо “Не делай так…”)

  • Объясните свои причины, почему вы думаете, что код должен быть изменен. (Не в соответствии со стилевым гайдом? Личное предпочтение?)

  • Предлагайте пути упрощения или улучшения кода.

  • Избегайте использования унизительных слов, таких, как “глупый”, когда ссылаетесь на работу, которую кто-то проделал.

  • Будьте скромны. (“Я не уверен, давай попробуем…”)

  • Избегайте использование гипербол. (“НИКОГДА не делай…”)

  • Стремитесь развить профессиональные навыки, общие знания и качество продукта, посредством групповой критики.

  • Не забывайте про негативный оттенок при онлайн-общении. (Если содержание нейтрально, то мы предполагаем, что тон задан негативный). Можете ли вы использовать более позитивный язык, вместо нейтрального?

  • Используйте emoji для пояснения тона. Сравните “Как писать отличные пулл-реквесты Как писать отличные пулл-реквесты Выглядит неплохо Как писать отличные пулл-реквесты Как писать отличные пулл-реквесты Как писать отличные пулл-реквесты” и “Выглядит неплохо.”



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



  • Рассмотрите возможность начать с выражения благодарности. Особенно, если фидбек получился неоднозначным.

  • Просите уточнить. (“Я не понимаю, не могли бы вы уточнить?”)

  • Уточняйте, поясняйте решения, которые вы принимали, чтобы прийти к решению вопроса.

  • Пытайтесь ответить на каждый комментарий.

  • Ссылайтесь на все соответствующие коммиты или пулл-реквесты. (“Отличное решение! Реализовано в 1682851”)

  • Если есть растущее непонимание или обсуждение, спросите себя, лучшим ли способом продолжения общения будет текст. Поговорите (виртуально) лицом к лицу, затем совместно обдумайте опубликование итогов для резюмирования оффлайн-обсуждений (удобно для тех, кто будет пытаться понять, сейчас или в будущем).


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

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

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

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

Источник: Хабрахабр

Категория: Программирование / Веб-разработка

Уважаемый посетитель, Вы зашли на сайт как незарегистрированный пользователь.
Мы рекомендуем Вам зарегистрироваться либо войти на сайт под своим именем.

Добавление комментария

Имя:*
E-Mail:
Комментарий:
  • bowtiesmilelaughingblushsmileyrelaxedsmirk
    heart_eyeskissing_heartkissing_closed_eyesflushedrelievedsatisfiedgrin
    winkstuck_out_tongue_winking_eyestuck_out_tongue_closed_eyesgrinningkissingstuck_out_tonguesleeping
    worriedfrowninganguishedopen_mouthgrimacingconfusedhushed
    expressionlessunamusedsweat_smilesweatdisappointed_relievedwearypensive
    disappointedconfoundedfearfulcold_sweatperseverecrysob
    joyastonishedscreamtired_faceangryragetriumph
    sleepyyummasksunglassesdizzy_faceimpsmiling_imp
    neutral_faceno_mouthinnocent