CONTRIBUTING.md

CONTRIBUTING

1. Репорт багов
2. Введение
3. Приступая к работе
4. Знакомство с командой
   1. Ведущий Разработчик
   2. Мейнтейнеры
   3. Разработчики
5. Добавление переводов
6. Гайды по разработке
7. Процесс открытия Pull Request
8. Портирование фич/спрайтов/звуков/инструментов с других кодбаз
9. Запрещенный контент
10. Пару слов о Git

Репорт багов

Если вы столкнулись с ошибкой в игре, лучший способ сообщить о ней кодерам - это наш GitHub Issue Tracker. Убедитесь, что вы используете прилагаемый шаблон проблемы, и укажите ID раунда. Если у вас нет учетной записи, создание новой займет всего одну минуту.

Если у вас возникли трудности, обратитесь за помощью в канал #разработка-bs в нашем Discord канале.

Введение

Приветствуем и добро пожаловать на страницу вклада нашего проекта SS220, билда BandaStation.

Каждый может внести свой вклад в этот проект, если он следует простым рекомендациям и требованиям описанным ниже; мы стремимся поддерживать стабильность и качество кода и для этого нам нужно, чтобы все пулл-реквесты соответствовали этим требованиям. В интересах всех - в том числе и ваших! - если одну и ту же ошибку не придется исправлять дважды.

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

Приступая к работе

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

Если вы хотите внести свой вклад, первое, что вам нужно сделать, это настроить Git, чтобы вы могли загрузить исходный код. После настройки опционально перейдите в командной строке git в папку с проектом и выполните команду: git config blame.ignoreRevsFile .git-blame-ignore-revs.

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

Также существует открытая база знаний, в которой собраны различные полезные гайды и программы для любого случая. Найти её можно в нашем канале #база-знаний-ss13.

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

Вы конечно можете попросить помощи, или совета в канале Discord #разработка-bs. Мы здесь только для того, чтобы получать удовольствие и помогать, так что, пожалуйста, не ждите профессиональной поддержки.

Знакомство с командой

Ведущий Разработчик

Ведущий разработчик координирует работу мейнтейнеров и участвует в принятии решений по развитию игрового сервера.

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

Мейнтейнеры билда

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

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

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

Разработчики

Разработчики - участники проекта с подтверждёнными навыками разработки, - отличившиеся лица с соответствующей ролью.

Они могут запрашивать изменения в вашем пулл-реквесте. Старайтесь не игнорировать их.

Гайды по разработке

Написание читаемого кода

Style guide

Написание здравого кода

Code standards

Написание понятного кода

Autodocumenting code

Прочее

• AI Datums
• Embedding TGUI Components in Chat
• Hard Deletes
• MC Tab Guide
• Policy Configuration System
• Quickly setting up a development database with ezdb
• Required Tests (Continuous Integration)
• Splitting up pull requests, aka atomization
• UI Development
• Visual Effects and Systems

Процесс открытия Pull Request

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

• Убедитесь, что ваш пулл-реквест соответствует требованиям, изложенным здесь.

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

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

• От вас будут требовать, чтобы вы документировали все свои изменения в пулл-реквесте. Если вы этого не сделаете, это приведет к задержке, так как нам придется задавать вопросы о том, почему вы внесли изменения. Вы можете ускорить процесс, сделав свой пулл-реквест читаемым и понятным, с данными "до/после". Если вы оптимизируете код, вы должны предоставить доказательства того, что ваши изменения работают быстрее, с помощью профайлинга.

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

• Если вы предлагаете несколько изменений, которые меняют множество различных аспектов кода, вы должны разделить их на разные пулл-реквесты, чтобы облегчить их рассмотрение и отклонить/принять те изменения, которые будут сочтены приемлемыми. Если изменение большое (например больше 500 строк кода), постарайтесь разбить его на нескольких небольших пулл-реквестов, если это возможно.

• Если ваш пулл-реквест рассмотрен и ваши изменения были вмержены (добавлены) в игру, то добавленный вами код больше не принадлежит только вам, а всем; все могут работать над ним, но вы также можете поддержать или возразить против вносимых изменений, что, скорее всего, будет иметь больший вес, поскольку именно вы добавили это.

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

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

• После ревью открытого пулл-реквеста, мейнтейнеры могут перевести его в статус draft. Как только вы отработаете по их замечаниям, не стесняйтесь снова пометить пулл-реквест как Ready For Review.

Обоснование изменений

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

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

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

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

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

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

Портирование фич/спрайтов/звуков/инструментов с других кодбаз

Если вы портируете что-либо из других кодовых баз, вы должны отдать им должное. Обычно рекомендуется указывать их пулл-реквесте. Обратите внимание на то, какую лицензию они используют: портирование вещей из кодовых баз AGPLv3 и GPLv3 разрешено.

Что касается спрайтов и звуков, вы должны указать автора (или пулл-реквест с кодовой базы) и, возможно, саму кодовую базу. Все ресурсы /tg/station и BandaStation, включая иконки и звуки, находятся под лицензией Creative Commons 3.0 BY-SA, если не указано иное.

Добавление переводов

Переводы имён предметов (переменная "name" у "/obj/item") требуют отдельных файлов перевода.

Они хранятся в modular_bandastation/translations/public/ru_names/ - по одному .toml файлу на каждое имя. ru_names.toml генерируется автоматически при сборке, не редактируйте его напрямую.

Tombi для VSCode

При работе в VSCode - вы можете использовать рекомендованное расширение Tombi для большего удобства, подсветки синтаксиса, раннего выявления неверно заполненного файла перевода.

Для его установки: введите - @recommended в строке поиска окошка расширений Visual Studio Code, или найдите Tombi вручную.

Как добавить перевод для нового предмета используя VSCode

1. Выделите английское название предмета в редакторе (например fish).
2. Запустите задачу ru_names: new fragment from selection (Ctrl+Shift+P -> Run Task).
   • Можно назначить хоткей: Ctrl+Alt+N -> workbench.action.tasks.runTask -> ru_names: new fragment from selection.
3. В директории ru_names/ появится новый файл готовый для заполнения.

Структура файла

["fish"]
nominative    = "рыба"     # именительный  — Это (что?) рыба - обязательное!
genitive      = "рыбы"     # родительный   — Нет (чего?) рыбы
dative        = "рыбе"     # дательный     — Дать (чему?) рыбе
accusative    = "рыбу"     # винительный   — Вижу (что?) рыбу
instrumental  = "рыбой"    # творительный  — Работаю (чем?) рыбой
prepositional = "рыбе"     # предложный    — Думаю (о чём?) о рыбе
gender = "female"          # male / female / neuter / plural

Поле nominative является обязательным - остальные падежи используют его как fallback если не заполнены.

Запрещенный контент

Не добавляйте в пулл-реквест ничего из перечисленного ниже, иначе рискуете получить закрытие PR и возможную блокировку на внесение изменений:

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

Если чего-то нет в этом списке, это не значит, что это допустимо. Руководствуйтесь здравым смыслом.

Пару слов о Git

В этом репозитории используются окончания строк LF для всего кода, как указано в файлах .gitattributes и .editorconfig.

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

Примечание: VSC требует расширения, чтобы воспользоваться преимуществами editorconfig.

Stale label пулл-реквестов

Когда ваш PR помечен как "Stale" и вы хотите поспешить с его ревью, - сообщайте об этом в открытый чат разработки - #разработка-ss13 в Discord SS220. Постарайтесь воздержаться от пингов роли мейнтейнеров и разработчиков. Неоправданное использование этого пинга может сопровождаться таймаутом и направлением к модераторам за дальнейшие нарушения.

Не стесняйтесь общаться и получать отзывы в канале #разработка-bs, #ss13-трекер до того, как ваш PR станет неактуальным, чтобы повысить интерес и получить отзывы.