Как использовать GitHub как настоящий человек

Узнай немного этикета, чувак.

Наша репо-организация иногда бывает отстойной. Вот как сделать его менее отстойным.

Совершает

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

Тем не менее, мы можем решить это раз и навсегда, запомнив несколько рекомендаций, когда мы фиксируем что-либо на GitHub. И я имею в виду НИЧЕГО. Личные проекты, проекты на работе, даже проекты, которые, как вы думаете, никогда не увидят свет.

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

Делая коммит, я обычно следую этому короткому списку рекомендаций Криса Бимса, а также руководству по стилю git. Вот что я узнал:

Делайте коммиты атомарными. Что это значит? Fresh Consulting советует применять изменения по мере их внесения. Ваша фиксация должна вращаться вокруг ОДНОГО изменения или исправления. Если вам нужно добавить и в сообщение о фиксации, вы уже совершили слишком много.
В сообщении фиксации должно быть не более 50 символов. Почему? Более короткие тексты легче читать, например это предложение. Коротко и по делу.
Первое слово в сообщении о коммите пишите с заглавной буквы. Это обычно считается хорошим поведением большинством мерзавцев. Приговоры также выглядят более профессионально и их легче читать. (Видите здесь образец?)
Не ставьте точку в сообщении о фиксации. Оставляйте людей в напряжении. Оставьте их желать большего. Кроме того, вы хотите убедиться, что ваши 50 персонажей потрачены не зря.
Используйте сообщение об обязательной фиксации. Сделайте так, чтобы ваши коммиты звучали так, будто вы кому-то дали команду. Программирование обычно определяется как «приказ вашему компьютеру что-то делать», так что с таким же успехом можно поддерживать эту репутацию, не так ли?
Используйте тот же язык в сообщениях о фиксации. Кажется, что большинство людей предпочитают английский язык, но это не значит, что вы должны это делать. Что вам действительно нужно, так это быть последовательным. Не смешивайте фразы на одном языке с другим языком.

«Refactor mediumExample () function», «Удалить ненужную строку в bot.js», и «Добавить гем SASS в gemfile» - все это хорошие примеры простых для понимания атомарных коммитов. которые описывают действие, которое вы делаете, 50 или менее символами. Они могут показаться вам ненужной ерундой, но когда вам или кому-то другому нужно найти конкретное изменение, которое вы сделали в прошлом, они будут бесконечно благодарить вас.

README

Я видел так много проектов с тусклыми README, от этого меня тошнит. Предполагается, что вы продадите свой проект. Когда кто-то его читает, он должен за секунды заинтересоваться вашим проектом. Только после этого они рассмотрят возможность дальнейшего изучения этого материала.

Вот что я считаю необходимыми элементами в README:

Изображение заголовка (необязательно). Дайте людям возможность посмотреть. Им нужно с первого взгляда знать, что это за проект. Может, покажите им скриншот с логотипом сверху, это круто.
Название. Людям нужно знать, как называется ваш проект. Сделайте это очевидным и выделите его, чтобы люди запомнили его.
Некоторые значки (необязательно). Значки - это круто, правда? Это должны быть важные вещи, такие как статус сборки Трэвиса, покрытие кода, проверка Дэвида DM или что-то в этом роде.
Краткое описание. Двадцать слов или меньше. Это небольшое предложение должно резюмировать все, о чем идет речь в вашем проекте. По сути, это ваш слоган. Продайте свой проект.
Небольшой список возможностей. Четыре-пять фраз со словами: «Эй, вот что в этом проекте круто!». Заинтересуйте людей своим проектом некоторыми радикальными вещами, которые делает ваш продукт.
краткое описание установки и / или использования. Ваше приложение не должно занимать 10 абзацев, описывающих, как его установить и / или использовать, и вам не нужно писать целое руководство, чтобы быстро показать некоторым людям, как это работает. Напишите быструю версию TL; DR для установки и / или использования вашего проекта. Ничего особенного, достаточно, чтобы люди начали работать.
Внешние ссылки на дополнительную документацию. Вы ведь написали документацию для своего проекта? Верно? Верно ?! Если да, пожалуйста не указывайте здесь полностью. На GitHub есть вики-сайты для вашего проекта, которые обеспечивают гораздо лучший способ представления контента по сравнению с одним огромным файлом Markdown. Ссылка на некоторые важные статьи в красивом маркированном списке.

ветви

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

В этом руководстве по стилю git говорится, что вам следует использовать короткие и описательные имена, и я считаю, что это хороший ориентир для именования. Используйте что-то вроде rails-5-upgrade или используйте его для ссылки на конкретную проблему на GitHub, например issue-57. Сделайте так, чтобы название вашей ветки рассказывало историю с минимальным количеством персонажей и дало бы супер краткое описание того, что вы в ней делаете.

Кроме того, из любви к Торвальдсу, обновляйте свои ветки с помощью основной ветки. Меня не волнует, если это будет больно. Убедитесь, что когда вы отправляете PR, владельцу не нужно делать миллион обручей, чтобы объединить вашу ветку с мастером. Конфликт слияния? Почини это.

Проблемы

Давайте поговорим здесь об отчетах об ошибках. Вы когда-нибудь пытались что-то исправить, не зная, в чем проблема? Хм? Вы говорите, что это?

Вы не можете ожидать, что я что-то исправлю, не зная, в чем проблема.

Точно! Так много людей отправляют отчеты о проблемах на GitHub, ни черта не описывая. Описывайте свои проблемы. Это всем помогает.

Как вы искренне ожидаете, что кто-то поможет вам с вашей проблемой, если вы даже не можете найти время, чтобы ее описать? Вот несколько вещей, которые вы должны включить в отчет об ошибке, чтобы всем было проще:

Что вы пытались сделать. При каких условиях возникла эта ошибка? Вы пытались запустить команду или перейти на страницу? Так много вопросов, так мало времени. Приложите несколько снимков экрана или журнал, если можете.
Что произошло на самом деле. Вы знаете, как все запуталось.
Что, по вашему мнению, пошло не так (необязательно). Это как-то облажалось, не так ли? Угадай, почему.
Как воспроизвести проблему.
Другие важные детали. ОС, версия того, что вы использовали, несколько журналов, если они у вас есть, несколько снимков экрана. Помогите нам помочь вам.

Теперь, когда мы разобрались с этим, давайте поговорим о ответах на проблемы. Будьте вежливы. Скажите «пожалуйста» и «спасибо». Тот факт, что кто-то отправил плохой вопрос, не означает, что он плохой человек. Хорошее отношение к людям - это первый шаг к их сотрудничеству. Попытайтесь решить их проблему, запрашивая дополнительную информацию. Предлагайте решения, а не больше проблем.

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

Запросы на вытягивание

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

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

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

Теперь…

Бьюсь об заклад, вы собираетесь зайти в мои репозитории на GitHub и начать кричать на меня в Twitter о том, что я не следую своему собственному руководству. Вы правы, я не сейчас; Я написал это как руководство, которому нужно следовать, чтобы лучше совершать коммиты на основе того, что сейчас кажется модным и модным. Давайте вместе поправимся!