​

Перед началом

• Если вы не знакомы с рабочим процессом Git, пожалуйста, прочитайте наше руководство по Git и задавайте столько вопросов, сколько необходимо, в #howdoicode.
• Пожалуйста, ознакомьтесь с соглашениями C# (если работаете с C#) и нашими собственными соглашениями. Попробуйте прочитать, как отформатированы другие части кодовой базы, для общего понимания.
• Крупные новые функции и комплексные переработки существующих крупных функций (например, антагонисты или что-то, что можно считать подотделом) должны сначала быть предложены и приняты в абстрактном виде, прежде чем вы начнёте работать над их реализацией.
• Прочитайте Freezes and Restrictions issue и убедитесь, что ваш PR не мешает чему-либо или не требует специальных требований.
• Если вы исправляете баг, присутствующий на живых серверах, или решаете срочную проблему баланса на живых серверах, подумайте, должно ли ваше изменение быть hotfix.
  • Hotfix должны направляться в stable branch, поэтому для этого вам нужно ответвить свою рабочую ветку от stable, а не от master.
  • Вы всё равно сможете открыть свой PR на master branch, даже если вы ответвились от stable, но передумаете позже.
  • Однако такая рабочая ветка не будет показывать невыпущенные изменения, которые были смержены в игру с момента последнего релиза. Вы не увидите, мешает ли ваш код этим изменениям или конфликтует с ними. Это может стать проблемой, если цель вашего PR будет изменена на master branch. По этой причине изменения контента или функций следует основывать на master branch.

​

Содержание

• Делайте отдельные PR для изменений функций, исправлений багов и чистки/рефакторинга. Это упрощает ревью, уменьшает конфликты и упрощает откат, если что-то пойдёт не так.
  • Изменения функций и исправления багов должны быть в своих собственных PR.
  • Чистка и «рефакторинг», включая переименование переменных и изменения отступов (например, из-за file-scoped namespacing), должны быть в своём собственном PR.
  • Рефакторинг должен быть в отдельном PR. Это включает изменения, затрагивающие значительное количество публичных API (поля, методы и т.д.), требующие изменений в нескольких системах. Они должны быть сделаны в отдельном PR от любых изменений контента или исправлений багов.
  • Если вы перемещаете файл в другую папку и/или namespace, делайте это в отдельном commit, когда это возможно, чтобы было легче понять, что изменилось в файле, а что было просто перемещено.
  • Изменения карт должны быть в отдельном PR для каждой изменённой карты. Это касается даже незначительных изменений.
• Не вносите несколько несвязанных изменений в один PR. Например, не делайте разрозненных дополнительных изменений в PR, например, изменение теплостойкости пары перчаток вместе с вашим PR, добавляющим новое оружие.
  • Старайтесь разделять ваш PR на более мелкие части, где это имеет смысл. Это значительно упрощает чтение и может привести к более быстрым ревью. Это также обычно проще для вас и означает, что вы получите раннюю обратную связь и сможете избежать траты времени на изменения, которые нужно переделывать.
• Начинайте каждый PR с краткого описания того, что он делает, простыми словами, и, если это геймплейный PR, ссылайтесь на соответствующие design documents. Возможность быстро увидеть, что ваш PR намеревается сделать и как он относится к установленным design documents, ускоряет триаж и ревью. При отправке небольшого изменения или когда нет подходящего существующего design document, дизайн может быть изложен непосредственно в описании PR.

​

Тестирование

• Тестируйте все ваши изменения в игре. Все исправления багов и функции должны быть протестированы в игре. Вы также должны тестировать другие функции, которые могут быть косвенно затронуты вашими изменениями.
  • По вышеуказанной причине не используйте веб-редактор GitHub для создания PR. Правки через веб-редактор могут быть закрыты на усмотрение maintainer. Повторная отправка PR, сделанных через веб-редактор, может привести к бану в репозитории.
• Предоставляйте скриншоты или видео, демонстрирующие проведённое тестирование. Это также упрощает написание отчётов о прогрессе.

​

Перед отправкой

• Решите/подтвердите, является ли ваше изменение срочным hotfix.
  • Hotfix не ждут следующего двухнедельного релиза после слияния.
  • Баги, влияющие на живой сервер, или срочные изменения баланса могут считаться hotfix.
  • Только изменения, основанные на stable branch, могут стать hotfix.
  • Когда вы открываете PR на GitHub, вы можете выбрать, на какую ветку он будет направлен, и master branch выбирается по умолчанию. Для hotfix вы должны выбрать stable branch вручную.
  • Если вы не уверены, должно ли ваше изменение быть hotfix, откройте его, нацелив на master branch. Затем спросите в PR, можно ли сделать его hotfix.
• Решите, открываете ли вы PR как draft.
  • Draft PR разрешены только в том случае, если часть PR требует ревью и/или одобрения, чтобы другие сегменты того же PR могли быть завершены.
  • Draft PR не должны открываться, если PR просто не завершён и не готов к ревью.
  • Несоблюдение этого может привести к закрытию вашего PR.
• Просмотрите ваш diff с помощью вкладки предпросмотра кода на GitHub.
  • Проверьте изменения, которые вы не намеревались коммитить.
  • Проверьте случайные добавления пробелов или изменения концов строк.

​

Заполнение шаблона PR

1. Секция About должна объяснять только то, что делает PR.
2. Секция Why/Balance должна обосновывать изменения в вашем PR.
   1. Небольшие исправления багов не нуждаются в пространном обосновании.
   2. Если pull request ориентирован на баланс, обоснование должно правильно объяснять почему изменение необходимо.
   3. Обоснования, которые только объясняют, что pull request делает или эффекты от изменений, не принимаются.
   4. Крупные добавления контента должны соответствовать основным принципам дизайна. Достаточно крупные добавления контента могут потребовать design document для детализации более широкой цели изменений и того, как они вписываются в текущую игру.
3. Секция Test Plan должна объяснять, как тестировать изменения.
   1. Опишите, как вы тестировали изменения. Подумайте, как кто-то другой, глядя на этот pull request, может проверить, что он работает как задумано.
   2. Если вы исправляете баг, желательно поделиться шагами для его воспроизведения, как он был сломан раньше и как он исправлен с вашим pull request.
4. Секция Technical Details должна давать обзор изменений высокого уровня.
   1. Это более важно при исправлениях багов или крупных рефакторингах. Предоставление обзора ваших изменений и технических решений, которые вы приняли, помогает нам просматривать изменения; в противном случае нам приходится самим определять, почему было сделано изменение, что сильно увеличивает время обработки.
5. PR должен иметь media, когда это применимо.
   1. Изменения, касающиеся визуала, механики или исправления багов, должны иметь прикреплённые медиафайлы для демонстрации изменений Maintainers и сообществу.
   2. Если медиа отсутствует, возникают сомнения, тестировали ли вы ваше исправление.
   3. Медиа обычно не требуется, когда исправление интуитивно очевидно из чтения изменений кода (например, инвертированная булева логика).
6. Секция Breaking Changes должна быть заполнена, если применимо.
   1. Breaking changes происходят, когда изменяется следующее:
      1. Был изменён публичный API. Это включает изменения имён полей данных YAML.
      2. Код был перемещён в другой namespace, или namespace был изменён.
      3. ID prototype были изменены или удалены (даже если ID были мигрированы).
   2. Breaking changes должны включать полезные советы по их исправлению, если это сложно. Приветствуются простые перенаправления, такие как «Используйте namespace x», «Используйте Entity<T> вместо», «используйте хелперы RefactoredSystem».
7. Секция Changelog должна быть заполнена, если применимо.
   1. См. секцию Changelog в нижней части этого документа для получения дополнительной информации о том, как заполнять changelog.

​

После отправки

• Не делайте force push в вашу ветку после получения ревью, если только maintainer не попросит об этом. Это приводит к тому, что все ревью отображаются как «устаревшие», даже если они ещё не были учтены.

​

Ревью

​

Получение ревью

• Любой желающий может просматривать PR. Ревью от других контрибьюторов могут быть так же ценны, как и ревью от maintainers, и часто означают, что PR могут быть смержены быстрее и помогают снизить нагрузку на maintainers. Если вы ждёте ревью, возможно, стоит найти другого контрибьютора в аналогичной ситуации, чтобы вы могли взаимно просматривать PR друг друга. Чтение чужих PR и критическое мышление о том, как бы вы написали код, также может быть полезным обучающим инструментом.
• Maintainers периодически просматривают открытые PR.
• Если прошло несколько дней, а первоначального ревью всё нет, уместно попросить ревью в #pr-review-request.

​

Ответ на ревью

• Когда вы отвечаете на ревью, нажмите «Resolve conversation» на GitHub после того, как ваш исправленный код был запушен.
• Если у вас есть вопросы по ревью, оставленным на вашем PR (или по вопросам кода в целом, конечно), не стесняйтесь спрашивать разъяснения на GitHub или Discord у ревьюера или в #howdoicode.

​

Changelog

​

Шаблон Changelog

:cl:
- add: Added fun!
- remove: Removed fun!
- tweak: Changed fun!
- fix: Fixed fun!

​

Категории Changelog

​

Changelog карт

:cl:
MAPS:
- add: Added fun!
- remove: Removed fun!
- tweak: Changed fun!
- fix: Fixed fun!

:cl:
MAPS:
- add: On Meta, a new laser tag arena has been added to north-eastern maints.
- remove: On Bagel, the evac security checkpoint's ID card terminal has been removed.
- tweak: On Box, the AI core has been moved to the center of the station, underneath the Bridge.
- fix: On Fland, the SMES array has been rewired to charge properly.

:cl:
MAPS:
- remove: On many stations, the anomaly generator has been removed.
- remove: On all stations, the cargo shuttle control terminal has been removed.

:cl:
MAPS:
- add: Added a new station, RA-12 Spire, a midpop engineering-focused tesla-centric station.
- add: Added a new station, Gate, a highpop fractured station. 
- remove: Core station has been removed.

​

Admin changelog

:cl:
ADMIN:
- add: Added fun!
- remove: Removed fun!
- tweak: Changed fun!
- fix: Fixed fun!

:cl:
- add: Added fun!
- remove: Removed fun!
- tweak: Changed fun!
- fix: Fixed fun!
ADMIN:
- add: Added fun!
- remove: Removed fun!
- tweak: Changed fun!
- fix: Fixed fun!

​

Написание эффективного Changelog

1. Записи должны быть полными грамматически правильными предложениями. Они должны начинаться с заглавной буквы и заканчиваться точкой.
   • Не очень хорошо: «fixed reflected projectiles dealing stamina damage» — предложение не начинается с заглавной буквы и не заканчивается точкой.
   • Не очень хорошо: «Wide attacks no longer cost stamina, deal weapon damage.» — висящая конструкция после запятой.
   • Не очень хорошо: «There is now more structures that can be made out of web» — отсутствует точка в конце предложения, и поскольку «more structures» во множественном числе, правильное спряжение глагола — «are». Но всё это предложение можно переписать в активном залоге, например: «More structures can now be made out of web»
   • Не очень хорошо: «A craft for cloth consisting of silk.» — это не полное предложение.
2. Логируйте только изменения со значительным игровым эффектом. Это может включать новые функции или изменения или твики существующих функций, влияющие на баланс. Незначительные изменения внешнего вида предметов и описаний обычно не влияют на то, как вы играете в игру. Записи changelog для крупных обновлений спрайтов уместны.
   • Хорошо: «The R&D server can be deconstructed. Be warned: this resets all unlocked technology, points, and the current discipline.» Без записи в changelog игроки могут не знать, что сервер R&D теперь можно демонтировать. Это также предупреждает их о потере технологий, чтобы они не были застигнуты врасплох.
   • Не очень хорошо: «Adjusted pickaxe inhand sprites and added sprites for wielded pickaxes.» — вы увидите изменения, когда решите взять кирку в руки. Знание того, что кирки выглядят иначе, не изменило бы вашу стратегию предателя.
   • Не очень хорошо: «Changed the plating sprite to be a little less blue.» — по той же причине.
3. Используйте настоящее время, активный залог.
   • Не очень хорошо: «HAMTR mech has been added.»
   • Хорошо: «The roboticist can now build the HAMTR mech.» — переписывание этого предложения в активном залоге сделало его более увлекательным и включило больше релевантных деталей.
   • Не очень хорошо: «Added candy bowls for waiting lines.» — Кто добавляет?
   • Хорошо: «Candy bowls can now be found near waiting lines.» — Подлежащее теперь «candy bowls». Каждое предложение имеет подлежащее и глагол.
4. Будьте кратки и избегайте многословных, «ролевых» изменений. Игроки должны понимать суть изменений, просматривая Changelog. «Ролевые» изменения сложнее читать и понимать. Делайте изменения краткими и по существу. Если им нужна дополнительная информация, они могут обратиться к guidebook. Избегайте спама несколькими связанными изменениями в разных строках. Если несколько видов оружия безопасности были перебалансированы, просто скажите об этом, чтобы игроки знали.
   • Не очень хорошо: «Central has distributed a new subversion of the standard particle accelerators. Nothing exciting, but they have brought back the old wiring layout. Apparently some of the newer versions were having firmware issues and it was more reliable. Keep on eye on it while it”s running will you? We don”t want an intern disabling the safeties and frying their face off.» — Вы понимаете, что изменилось? Даже автор считает изменение «ничего захватывающего».
   • Не очень хорошо: «Due to budget cuts, detective’s revolver has been replaced with something more appropriate.» — Что более «appropriate»?
   • Хорошо: «The detective’s revolver now contains cap bullets instead of lethals.»
   • Не очень хорошо: «The Syndicate has changed around their stock prices and gotten rid of some old dusty headsets» — Непонятно, что изменилось и как это связано с «stock prices» и «dusty old headsets».
   • Хорошо: «The syndicate headset has been removed from the uplink.» — Чётко объясняет, что было изменено.
   • Не очень хорошо: «Due to Nanotrashen’s budget cuts, Space pens are no longer supplied on the station.»
   • Хорошо: «Space pens are no longer available.»
5. Избегайте технического жаргона.
   • Не очень хорошо: «Fixed microwaves defaulting to 5 seconds when the ui said instant.» — Что такое ui? Можно улучшить, используя общепринятую аббревиатуру «UI». Кстати: действительно ли instant теперь мгновенный, или просто по умолчанию 5 секунд?
6. Задавайте правильный тон.
   • Не очень хорошо: «Can you believe it? Arachnid re-rework just dropped! Check the PR for more details»
   • Не очень хорошо: «Arachnids have new sprites for being creampied.» — creampied имеет другое, неудачное значение, которое подрывает профессиональный тон записи changelog.