STYLING_OF_PR.md

Оформление Pull Rrequest-ов

Введение

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

Что такое ПР?

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

TL;DR

Попытавшись создать ПР вы увидите следующий шаблон, самое главное - следуйте ему:

• Описание изменений
  • Опишите изменения данного ПР-а. Если есть связные ишью (issues), или другие ПРы - укажите их тут, для автоматического закрытия ишью следует использовать ключевые слова https://help.github.com/en/articles/closing-issues-using-keywords Если есть связное форумное обсуждение на тему изменений - укажите ссылку на эту тему.
• Почему и что этот ПР улучшит
  • Опишите причину для изменений. Этот пункт особенно важен для описания изменений баланса, новых механик.
• Авторство
  • Опциональный пункт! Если авторство не полностью ваше, вы делаете порт с другого билда - обязательно укажите первоисточник изменений! Для крупных комплексных изменений достаточно будет указать билд(ы)-первоисточник, в остальных случаях можете указать исходный ПР.
• Чеинжлог
  • Опциональный пункт! Если это что-то, о чём следует сообщить игрокам - опишите по форме #Changelog свои изменения для игрового чеинжлога, они будут отображены на специальной страничке http://changelog.taucetistation.org

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

Название

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

Важно

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

Описание

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

Как создать спойлер

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

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

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

Важно

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

Авторство

Если ваша работа или её часть не оригинальны, стоит отдать дань уважения автору в описании PR-а. Иногда это обязательно в соответствии с лицензией.

Если спрайты/звуки вам создал другой человек - укажите (стоит в т.ч. и в чеинжлоге, про это в следующей части).

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

Если вы используете сторонние звуковые файлы с саунд-библиотек - укажите ссылку на файл в этой библиотеке. Это важно как для автора, так и нам, чтобы проверить совместимость лицензии.

Вопрос лицензирования сложный для освещения в этом гайде, и чаще всего не требуется для изучения, но, если быть кратким:

• Все звуки должны быть под Creative Commons 3.0 BY-SA (сокращенно CC 3.0 BY-SA), или под совместимой свободной лицензией.
• Нельзя портировать с билда Goonstation, они имеют не совместимую с остальными билдами лицензию. Исключение - если вы договоритесь с автором напрямую о релицензировании его части. Остальные мейнстрим билды (tg, paradise), как правило, с совместимой с нами лицензией, и таковой проблемы не имеют.
• Можете спрашивать в #rnd по вопросам лицензии, если не уверены.

Changelog

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

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

: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 или add: Разные добавления и новшества (например, фичи).
• rscdel или del: Откаты фичь, удаление старого и т.д.
• image: Изменения со спрайтами и изображениями.
• sound: Звуки и всё что с ними связано.
• spellcheck: Небольшие или не очень исправления в тексте.
• tweak: Преимущественно небольшие изменение чего-то готового.
• balance: Изменения, связанные с балансом.
• map: Изменения на карте.
• performance: Производительность, скорость работы и т.д.
• experiment: Экспериментальные изменения, шанс отката которых выше обычного.
• localization или ru: Перевод на русский язык.

Что делать если изменений слишком много

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

: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 и так далее. Но при этом есть важный момент, автолэйблинг происходит лишь в момент создания ПРа. Поэтому, большая рекомендация и просьба, создавать ПР и писать к нему описание с чейнджлогом разом, а не частями. Особенно, если это описание вы добавляете сразу после создания ПРа.