Styling of Pull Requests for Dummies - GammaStation/Gamma-Station GitHub Wiki

1. Введение
2. Что такое ПР?
3. Название
4. Описание
5. Чейнджлог
6. Важно

Данная статья не носит в себе цели научить вас создавать ПРы, объяснить, что это такое с нуля, показать какие кнопки нажимать, чтобы ПР появился и так далее. Всё это уже много раз и много где расписано. Поэтому поищите в гугле, на нашей вики или ещё где, здесь про это не будет сказано ни слова. Цель данной статьи - расширить вещи, описанные тут, а также рассказать про некоторые нюансы о которых нигде нет ни слова. Преимущественно здесь будут подняты вопросы оформления.

В двух словах: вы сделали работу, вы представляете её на обозрение в виде запроса. Ключевое слово "представляете". Вы можете накодить убер сложную и интересную фичу. Это круто. Но если вы не расскажете в ПРе как эта фича работает, то скорее всего его не смержат. Нулевое описание обязывает ревьюера читать ваш код тщательней. Если код очень сложный, то просто на то, чтобы понять контекст придётся потратить не малое время. Это плохо, потому что мейнтейнерам за их время никто не платит и всё происходит на добровольных началах. Войдите в чужое положение и потратьте дополнительные 15 минут на оформление реквеста. Вы покажете себя с очень хорошей стороны, да и в принципе это ведь в ваших интересах, чтобы ПР быстрее смержился.

Пулл Реквест, как правило, состоит из трёх основных элементов: название, описание, чейнджлог. Далее о каждом элементе в деталях.

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

• Не давайте слишком длинных названий. Слишком длинное - это название, которое не вмещается в выделенное гитхабом место и разбивается на части, частично залезая в основное тело описания ПРа.
• Название так или иначе обязано передавать суть ПРа. Даже если в контексте каких-то обсуждений в конференциях название кажется вам самодостаточным, всё равно нет. Что-то из формата "ы, сматрите чё сделал" или "Спасибо ~~~'у за победу" - недопустимо.
• После написания названия прочтите его и попробуйте определить, что происходит в ПРе с позиции другого человек.
• Используйте дополнительные теги [WiP] и [DNM]. Первое это Work In Progress, означает, что ПР не готов и вы создали его, например, для предварительного обсуждения изменений. Второе это Do Not Merge. Этот тег пригодится, например, если ПР ваш закончен, но в нём вы сделали нечто экстремальное и мир ещё к этому не готов. Кроме того, бот, подключённый к нашему репозиторию, увидев эти теги автоматически поставит вашему ПРу соответствующие лэйблы. Оба тега можно использовать в одном названии.
• Не используйте ключевые слова, распознаваемые гитхабом. Подробнее о них тут.

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

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

<details> 
  <summary>Заголовок спойлера</summary>
  Текст под спойлером.
</details>

Disclaimer: внутри конструкции гитхаб не рендерит свою разметку, поэтому нужно использовать html теги.

• Именно в описании нужно использовать ключевые слова гитхаба типа fixes, closes и так далее. Весь список представлен по ссылке тут.
• Не забывайте про форматирование. Пробелы, переходы на новые строки, абзацы и всё такое прочее.

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

Чейнджлог генерируется автоматически, после мержа пулл реквеста. Генерация происходит на основе специальной разметки, добавленной прямо в тело основного описания ПРа. Далее будет приведён пример лога.

:cl: SpaiR
 - bugfix: Боргам выдавался неправильный модуль при их емаге.

Разберём что здесь есть.

1. :cl: Это своеобразный маркер для бота. Начиная с него весь текст ниже будет восприниматься как часть чейнджлога. Но сам по себе маркер суть эмодзи, который выглядит примерно так 🆑 (может отличаться в зависимости от браузера, ОСи и фазы Луны).
2. SpaiR Имя, которое будет добавлено в чейнджлог. То есть, читая лог будет видно, что такие-то изменения были сделаны вот этим вот человеком. Указывать этот ник не обязательно, т.к. по умолчанию бот будет брать ваш никнейм на гитхабе. Но если с игровым они отличаются или вы, не дай бог, хотите скрыть свою личность, то можете им воспользоваться.
3. - bugfix: Это начало записи, которая будет добавлена в чейнджлог. Именно в таком виде, с таким количеством пробелов и такими символами она воспринимается ботом. bugfix - классификатор записи. В данном случае он указывает на то, что фиксится баг. Классификаторы бывают разные, чуть ниже будет указан их полный список с описанием что для чего нужно использовать.
4. Боргам выдавался неправильный модуль при их емаге. Очевидно, это лог сделанного вами изменения видного в игре.

Другой пример чейнджлога.

:cl:
 - image: Добавлен плакат с изображением статного мужчины с конусом на голове и арбузами вокруг него.
 - image: С плаката чужого в форме горничной убрана цензура.

Отличия от предыдущего лога следующие:

1. Не указан никнейм. Как было отмечено выше, это опциональная фича. Если вас устраивает, что в лог попадёт ваш ник гитхаба, ничего можно не писать.
2. Использован классификатор image вместо bugfix. Здесь он указывает на то, что добавлены новые спрайты.
3. Две записи вместо одной. Всего записей может быть неограниченное количество. Важный момент, внутри одной записи не должно быть явных переходов на новую строку. Под явными переходами имеется ввиду нажатие клавиши enter и подобного. Запись может не вмещаться в пространство, выделенное гитхабом на одну строку, тогда она расползётся на две/три и так далее, но это допустимо.

Важная часть чейнджлога это: - классификатор:. Пробел перед тире, после тире и после двоеточия. Необходимо соблюдать именно такую последовательность. Автоматический обработчик использует её для парсинга и нахождения новых записей в лог. Чтобы понять не допустили ли вы ошибки посмотрите на результат в превью, чейнджлог должен выглядеть как список. Возвращаясь к примерам, в теле описания они должны выглядеть так:

🆑 SpaiR

• bugfix: Боргам выдавался неправильный модуль при их емаге.

И...

🆑

• image: Добавлен плакат с изображением статного мужчины с конусом на голове и арбузами вокруг него.
• image: С плаката чужого в форме горничной убрана цензура.

• bugfix: Фиксы. Рекомендуется писать в форме "Было ..." или "Стало ...". Не нужно писать "Исправлен баг ..." и так далее. Из классификатора понятно, что баг был именно что исправлен. Например, Исправлен баг с возможностью ходить сквозь стены превратится в это Убран эксплойт с хождение сквозь стены. Рекомендация связана с тем, что в ином случае чейнджлог просто пестрил бы словами исправлено, пофикшено и прочими им подобными.
• rscadd: Разные добавления и новшества (например, фичи).
• rscdel: Откаты фичь, удаление старого и т.д.
• image: Изменения со спрайтами и изображениями.
• sound: Звуки и всё что с ними связано.
• spellcheck: Небольшие или не очень исправления в тексте.
• tweak: Преимущественно небольшие изменение чего-то готового.
• balance: Изменения, связанные с балансом.
• map: Изменения на карте.
• performance: Производительность, скорость работы и т.д.
• experiment: Экспериментальные изменения, шанс отката которых выше обычного.

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

:cl:
 - rscadd[link]: Добавлен новый атмос.

Ключевая вещь здесь - [link]. Это маркер, который, когда встречается боту при создании чейнджлога, указывает тому вставить в запись лога ссылку на ПР. Более от вас ничего не нужно, бот сам разберётся куда ссылка будет вести и добавит её в конец записи. В метку ничего помещать не нужно. Важно: маркер должен располагаться именно в том месте, которое продемонстрировано в примере (сразу после классификатора, перед двоеточием) и нигде более.

• Старайтесь делать чейнджлог компактным, но информативным.
• Не стесняйтесь использовать несколько записей, если описываете логически разные вещи.
• В случае вопросов задавайте их в канала [#rnd]. Лучше спросить, чем потом уклоняться от помидоров.
• Не используйте сленговых слов. Не критично, но старайтесь быть классным во всём.

Бот умеет делать первичную проверку чейнджлога на корректность оформления. Если вы что-то сделали неправильно, то вашему ПРу будет добавлен лэйбл Invalid Changelog, а также появится комментарий с типом ошибки. После исправлений лэйбл автоматически будет снят, но комментарий останется.

Неправильная разметка, может выглядеть так:

:cl: - Тут описаны изменения

Что здесь неправильно нету смысла писать, проще сказать, что единственное что здесь верно - это эмодзи :cl:. Кажется странным и непонятным как такое возможно, но прецеденты были.

Ещё вариант неправильной разметки может быть такой:

:cl:
-bugfix: Тут описаны изменения.

Здесь неправильно расставлены пробелы. Определить подобный тип ошибки легко - гитхаб не отформатирует такой лог как список. Также, бот оставит коммент в котором будет ругаться на пустой чейнджлог (для него он будет именно что пустым).

Более приземлённый вариант - очепятка:

:cl:
 - bufgix: Тут описаны изменения.
 - rscad: Тут описаны изменения.

Бот оставит коммент с указанием какие классификаторы указаны неверно. В данном случае все.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam at tellus a ligula commodo viverra. 
Aliquam gravida ornare convallis. Suspendisse elementum rhoncus orci id hendrerit. Sed ut est porttitor, porttitor urna nec, vehicula lacus. Pellentesque nec imperdiet mi, at aliquam ante. 
Suspendisse tristique porttitor congue. In vel nisl eget purus cursus ultricies. Sed sollicitudin tortor leo, nec dictum felis pulvinar eget. Etiam luctus arcu aliquam scelerisque lobortis. 
Pellentesque auctor interdum eleifend. 
Donec quam metus, vulputate non ex sed, pulvinar tempus lorem. Praesent egestas quam a egestas ultrices.

:cl:
 - rscadd: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 - rscadd: Nullam at tellus a ligula commodo viverra.
 - bugfix: Pellentesque auctor interdum eleifend.
 - rscadd[link]: Praesent egestas quam a egestas ultrices.

Как уже была сказано, к репозиторию подключён бот. Одна из фич которые он может делать - это автоматически добавлять лэйблы к ПРу. Данная функция облегчает работу мэйнтейнерам, убирая довольно рутинную работу. Список лэйблов, которые будут повешены на ПР формируется исходя из чейнджлога. Например, rscadd - это лэйбл Feature, bugfix - Fix и так далее. Но при этом есть важный момент, автолэйблинг происходит лишь в момент создания ПРа. Поэтому, большая рекомендация и просьба, создавать ПР и писать к нему описание с чейнджлогом разом, а не частями. Особенно, если это описание вы добавляете сразу после создания ПРа.