Как отправить хорошие запросы на GitHub

1 min


За последние несколько лет я написал или рассмотрел тысячи GitHub pull
запросы (PR), как для работы, так и для личных проектов. Я поверил
есть небольшой набор полезных практических правил для того, что делает хороший пиар, что
делает плохой пиар, и почему объединение хороших гораздо проще – как для
пиарщик и рецензент.

Вот краткий контрольный список для хорошего пиара. Каждый предмет описан более подробно
ниже.

  1. Убедитесь, что пиар нужен
  2. Есть открытый вопрос, связанный в (необязательно)
  3. Напишите полезный PR заголовок
  4. Напишите подробное описание PR
  5. Придерживаться стандартов кодирования проекта
  6. Добавить тесты
  7. Убедитесь, что все тесты пройдены
  8. Будьте терпеливы и дружелюбны во время проверки кода

Убедитесь, что пиар нужен

Это особенно важно, если вы вносите вклад в хранилище, которого у вас нет
работал много раньше. Проведите некоторое исследование существующих проблем и PR в
хранилище – в том числе закрытое. Это изменение уже обсуждается
где-то? Было ли это предложено ранее и отклонено? Код, который вы хотите изменить – это
это не зря?

GitHub предлагает достаточно хорошие возможности поиска в случае, если проект имеет
большой журнал вопросов в PR. Это не идеально, но запустив несколько поисков с
вероятные ключевые слова, есть хороший шанс что-то найти. Другое дело, я часто
сделать это поиск истории фиксации проекта для соответствующей информации (мерзавец
--grep
).

Демонстрация некоторой должной осмотрительности имеет большое значение в показе владельца хранилища
что ты серьезный вкладчик.

Есть открытый вопрос, связанный в (необязательно)

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

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

Если есть сомнения – откройте вопрос. Добавьте весь контекст там. PR будет тогда
ссылаться на проблему с # тег – это что-то GitHub
понимает и добавит ссылку между ними. PR может также сказать Исправления
#
если слияние этого пиара означает, что проблема полностью решена.

Один из самых неприятных событий для сопровождающего хранилища – это получение
PR без достаточного контекста того, что он пытается решить и почему
, имеющий
открытый вопрос со всеми деталями – лучший способ установить этот контекст;
В следующих разделах рассматриваются некоторые дополнительные способы.

Я отметил этот раздел как (по желанию) потому что проблема не нужна в некоторых
случаев. Например, опечатки в комментариях обычно не требуют проблемы и PR
несет достаточный контекст. Незначительные изменения в документации также не требуют
проблемы в большинстве случаев.

Если есть сомнения, создайте проблему. Ссылка на предыдущий раздел – если проблема
описание проблемы уже существует, не забудьте связать с ней свой PR –
сопровождающие любовь PR, которые решают открытые вопросы.

Напишите полезный PR заголовок

Этот совет будет звучать как «что делает хорошее сообщение git commit».

Название PR чрезвычайно важно. Это то, что люди видят, когда перечисляют все открытые
Реципиентов. Это также обычно переводится как первая строка объединенного коммита,
и проявляется заметно в мерзавеци т. д. Будьте особенно внимательны при изготовлении
Название PR должно быть наглядным и полезным, но не слишком длинным.

В некоторых крупных репозиториях есть специальные рекомендации по написанию PR. Например,
PR-заголовок будет начинаться с имени компонента – «Хранение / удаленный:
увеличить время ожидания виджета "
, Посмотрите вокруг – как работают другие пиарщики (которые были
удачно слился) посмотришь? Есть ли в репозитории какое-либо руководство
что детализирует эти условности?

Напишите подробное описание PR

Это тесно связано с рекомендацией «Имейте открытую проблему, связанную в». Если пиар
требуется подробное описание фона, лучше сделать это в выпуске и
есть ссылка в пиаре. Если по какой-либо причине проблем не возникает, бремя ложится на
описание PR, чтобы объяснить мотивацию для изменения, и подход
взятый в этом.

Но PR и вопросы также для разных целей. Иногда пиар описание
будет иметь информацию, которая не относится к проблеме, такие как детали
конкретный подход, принятый в PR, контрольные цифры для этого PR и т. д.

Описание PR попадет в журнал git commit – добавьте как можно больше деталей
ты можешь. Mainainer хранилища может позже настроить журнал коммитов, чтобы они
уберите вещи, которые им не нужны; если сомневаетесь, добавьте больше деталей.

Придерживаться стандартов кодирования проекта

Есть ли у проекта руководство для авторов? Потратьте пару минут на поиски
для этого.

Посмотрите на другие PR, которые были объединены – что сделали их авторы?

Посмотрите на некоторый существующий код в хранилище – попробуйте соответствовать стилю
Ваш PR в преобладающем стиле в существующем коде. Делая это показывает
Сопровождающий, что вы серьезный вкладчик, который заботится о долгосрочной перспективе
здоровье проекта.

Будьте внимательны к мельчайшим деталям: сколько пробелов имеет код,
в том числе в комментариях? Есть ли особый стиль написания – оксфордские запятые, один или
два пробела после точки и так далее?

Добавить тесты

Если вы добавляете новый код – убедитесь, что он проверен. Либо добавьте новые тесты, либо
укажите в описании PR, какие существующие тесты охватывают его. Если тест
слишком сложно добавить по какой-то причине, объясните почему.

Для изменения существующего кода ситуация немного более нюансирована. Это изменение
решение текущего теста провал? Который из? На какие тесты влияет
менять? Нужно ли добавлять новые тесты?

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

Убедитесь, что все тесты пройдены

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

После отправки пиара следите за этим и устраняйте любые сбои. Сопровождающие
вряд ли стоит обращать внимание на PR, которые нарушают сборку или тесты.

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

Будьте терпеливы и дружелюбны во время проверки кода

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

В обзорах кода написаны целые главы книги, поэтому я буду кратким и
Здесь все просто, с акцентом на вклады с открытым исходным кодом. При отправке пиара на работу
проект, очевидно, что мы должны быть очень дружелюбны и добры с коллегами,
правильно? Правильно?

Но как насчет открытого исходного кода? Вы обнаружили проблему в каком-то проекте OSS, который вы используете, и
отправляю пиар. Повезло тебе! Ожидаете ли вы, что сопровождающий будет в восторге?
о вкладе? Ну, не обязательно, и это действительно зависит от вашего
манера поведения.

Сопровождающие OSS общеизвестно перегружены работой и им недоплачивают. Иногда они просто
хотите стабильности – как можно меньше изменений. Ясно, если вы сообщаете о критическом
ошибка, они, вероятно, будут рады это исправить; но 99% ОР не для критических
ошибки – они для мелких ошибок и новых функций. Здесь пиар представляет
дилемма для сопровождающего – кто-то отправляет код, и этот кто-то очень
скорее всего собирается полностью исчезнуть после пиара земли, поэтому ответственность
код переходит к сопровождающему. Не удивительно, что во многих случаях
сопровождающие проявляют осторожность и даже подозрительно относятся к любым изменениям.

При ответе на комментарии комментируйте терпение и дружелюбие. Прими хорошее
намерения – сопровождающий берет на себя дополнительное бремя, чтобы поддерживать дополнительный код
(особенно с рекламными роликами), и это их право тщательно изучить и принять
их время Может потребоваться несколько раундов отзывов. Будьте уверены, чтобы быть отзывчивым
и внимательны к деталям – подтвердите все комментарии, либо выполнив
рецензент предлагает или (любезно) разъясняет вашу точку зрения. Добавьте больше тестов, если
они просят вас (и вы не можете указать на существующие тесты, охватывающие одно и то же),
добавьте больше комментариев, если они попросят вас.


0 Comments

Ваш e-mail не будет опубликован. Обязательные поля помечены *