Руководство по разработке

Пособие к Paracode: Гайд

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

Чтобы максимально удобно и эффективно вносить изменения в код вам будут нужны эти три вещи:

Текстовый редактор (VSCode крайне рекомендован)
Github
Сам BYOND редактор - Dream Maker

Быстрая навигация

Я абсолютный новичок
Мне нужно установить\настроить VS Code
Мне нужно настроить Git/Github
Я загрузил всё вышеперечисленное, как мне получить и настроить репозиторий?
Ок, у меня есть конфигурация репозитория, как мне менять содержимое?(Pull Requests)
Я хочу использовать Github Desktop (Дружелюбно к новичкам)
Я хочу использовать TortoiseGit (Не для новичков)
Ок, я завершил настройку своих изменений! Как мне закодировать/внести вклад на сервер?
Как мне создать Pull Request и отправить свои изменения через Desktop GitHub?
Я заметил ошибку, как о ней сообщить?
Я внёс свой вклад! Стоп, как вообще использовать TGUI?

Я абсолютный новичок

Итак, вы в ситуации, с которой сталкивался каждый разработчик Paradise. Как мне научиться работать и привносить свой вклад? Как мне добавить свой код к коду сервера? Что ж, тут несколько шагов, как начать работу и загрузить ресурсы.

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

Файл:ContributingFlowchart.png

Устанавливаем и настраиваем Visual Studio Code

Установка VScode

Идём на вебсайт VSCode's: https://code.visualstudio.com/
Загружаем и устанавливаем актуальную версию.

Установка VSCode плагинов

Когда вы откроете Paradise репозиторий, у вас появится уведомление об установке некоторых рекомендованных дополнений, они просто устанавливаются по данному алгоритму

Перейдите на вебсайт VScode и загрузите плагины
Нажатие "Установка" перенаправит вас в VSCode где вы можете установить и перезагрузить его

Вот пара плагинов, которые крайне полезны для кодинга в DM

Подсветка синтаксиса: https://marketplace.visualstudio.com/items?itemName=gbasood.byond-dm-language-support
Поиск символов: https://marketplace.visualstudio.com/items?itemName=platymuus.dm-langclient

Установка и настройка Github

Эта часть про установку и настройку Git и созданию Github аккаунта.

Установка Git Bash

Переходим: http://git-scm.com/downloads
Загружаем Windows Git программу, подходящую вашей операционной системе (оно должно будет выглядеть как "Git-2.18.0-64-bit.exe")
Устанавливаем его и оставляем всё в стандартном режиме (просто пропускаем всё кнопкой next).
Дожидаемся конца установки.
Готово!

Регистрируемся в Git

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

Переходим: https://github.com/
Нажимаем Sign up в правом верхнем углу.
Вводим свою почту
Придумываем пароль
Создаём себе крутой ник
Соглашаемся или отказываемся от рассылки.
Решаем капчу и создаём аккаунт!
Готово!

Скрываем свою почту (Опционально, рекомендуется)

Некоторые из вас не захотят показывать в своём резюме, что они работали над какими-то сомнительными проектами. Или более приближённо, сообщество SS13 мрачно и полно ужасов, и вам захочется защитить свою почту (или использовать подставную почту в первую очередь). О, и вам наверняка захочется редактировать ERP сервера под альтернативным именем.

По умолчанию включено, но лучше перестраховаться

Заходим в аккаунт на Github
В правом верхнем углу нажимаем на свой профиль
Появится список, выбираем "настройки"
Переходим к Emails
Включаем настройку Keep my email addresses private. Теперь Github будет использовать безответны письма при операциях.
Теперь вы защищены лучше!

Настраиваем Git (Опционально)

Переходим: https://help.github.com/articles/set-up-git/#setting-up-git
Следуя гайду выше, вы можете установить Git для Windows если хотите, однако это не рекомендуется
Теперь у вас есть полностью настроенный Git, но если вы неграмотны в написании кода, как я, то вам захочется иметь какую-нибудь причудливую графику!

Дополнительная помощь

Вспомогательные видео (на английском) для лучшего понимания Github

Введение в Git с Scott Chacon от GitHub
Git from bits up
Linus Torvalds (Тот парень, которой изобрёл Linux и Git)

Forking ParaCode

Понятие форкинга и репозитория:

Форкинг - создание своего ответвления от оригинального кода, создание репозитория

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

Теперь, посетите Paradise Github репозиторий Вам нужно будет нажать кнопку Fork в правом верхнем углу.

Ого, у вас теперь есть свой репозиторий! Фактически репозиторий - полная копия оригинального кода, отличие лишь в том, что они не связаны и любые ваши изменения не влияют на оригинал. Теперь, давайте скомбинируем ваш репозиторий и VS Code! Вернитесь в VS Code и перезапустите его. Под меню контроля ресурсов (выглядит как ветка дерева) нажмите Clone Repository. Это должно будет выглядеть так:

Если этой кнопки там нет, то вы можете нажать комбинацию Ctrl+Shift+P что бы открыть список команд, затем введите туда Git: Clone и нажмите enter.
Теперь, вставьте URL ссылку репозитория, который вы создали пару шагов назад. Для этого зайдите в свой репозиторий через меню профиля, а после возьмите ссылку страницы. Оно должно быть похоже на такую ссылку: https://github.com/ваше имя/имя репозитория Далее выберите папку, в которой будет хранится локальный репозиторий. Процесс загрузки может занять много времени, налейте себе чаю. После загрузки откройте эту папку в VS Code. Теперь у вас есть локальная копия кода!

Расширения VS Code

Нажмите на кнопку "Extensions" (расширения) на левой панели (выглядит как кучка квадратов), или нажмите комбинацию Ctrl+Shift+X. Вы должны будете увидеть количество рекомендованных расширений. Если нет, пропишите @recommended в поисковую строку. По крайней мере вы захотите установить необходимые расширений из списка ниже. Рекомендованные расширения не обязательны, но значительно облегчат вам работу.

Необходимые расширения

BYOND DM Language Support - подсветка синтаксиса для DM языка
DreamMaker Language Client - необычные функции, такие как отладка и переход к определениям
EditorConfig for VS Code - загружает стандартную конфигурацию редактора для кодовой базы
ESlint - предоставляет список для Javascript (этот необходим только если вы планируете работать с TGUI)

Добавляем Paracode как верхний репозиторий

Нам надо добавить главный Paradise репозиторий в качестве удалённого репозитория.
чтобы сделать это, откройте командную палитру, введите Git: Add Remote и нажмите enter. Далее, вам предложит ввести URL ссылку , а потом и имя удалённого репозитория. Вводим https://github.com/ss220-space/Paradise в качестве URL ссылки, и upstream в качестве имени. После завершения вы будете иметь главный Paradise репозиторий в качестве верхнего удалённого: Это позволит вам легко отправлять запросы о помощи позже.

Делаем изменения

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

Создание ветвей

Чтобы создать новую ветвь, откройте source control на боковой панели. Перейдите к More Actions menu (выглядит как ...) и нажмите Checkout to... , типа такого:

Теперь нажмите "Create new branch". В этом гайде я буду создавать новую шляпу, поэтому именем моей ветки будет hat-landia. If you look at the bottom left hand corner, you’ll see that VS Code has automatically checked out our branch: (нужен файл)
Запомните, никогда не изменяйте главную ветвь! Вы можете работать с любой веткой сколько вам угодно, пока фиксируете изменения в отдельной (новосозданной) ветке.
Вперёд! Меняйте код как хотите! Это гайд по тому, как вносить изменения, не по тому, что вам вносить! Так что я не расскажу вам как именно вам кодить, создавать спрайты или менять карту. Если вам нужна будет помощь, попробуйте спросить в канале #help-chat или дождитесь кого-то из кодеров в онлайне в дискорде.

Изменения кода

Вы можете найти код для редактирования во владке "Explorer" (два листа бумаги) в боковой панели; если вам надо найти файл или строку кода, и вы знаете его имя или расположение, то вы можете использовать поиск, он находится в боковой панели под Explorer.

Стиль старой школы: если вы хотите использовать DreamMaker вместо этого, можете редактировать их там - как только вы их сохраните, VS Code обновит ваши изменения и вы сможете продолжать следовать гайду здесь.

Теперь сохраняем свои изменения. Если вновь взглянем на контроль ресурсов (Source Control), мы увидим, что у нас появилось несколько изменений. Git нашёл каждое изменение, которое вы сделали со своим форком на вашем компьютере! Даже если вы изменили единственный пробел в одной строчке кода, Git найдёт это изменение. Просто убедитесь, что вы сохранили свои файлы.

Тестируем свой код

Самый простой способ протестить свои изменения, это нажать F5 или воспользоваться меню run and debug под контролем ресурсов. Это скомпилирует ваш код, запустит сервер и присоединит вас к нему, а так же выдаст вам права администратора. Это также запустит дебаггер, который поможет вам изучить, что могло пойти не так, когда ошибка закроет вам игру. Если вы хотите не запускать дебаггер, то нажмите Ctrl + F5 для запуска. Запуск сервера может занять длительное время, не надо постоянно останавливать и перезапускать запуск.

Это не сделает вас админом в игре автоматически, для этого вам надо скопировать всё из /config/example и вставить это в /config. Затем надо будет отредактировать /config/config.toml , добавив строчку {ckey = "ваше имя в byond", rank = "Hosting Provider"} в список admin_assignments.

Это компилирует код в dmb файл. Затем вы можете запустить Dream Daemon, выбрать файл dmb, установить Security(безопасность) на Trusted(Доверенное) и нажать GO, чтобы запустить сервер. После запуска сервера вы можете нажать на новую кнопку над кнопкой GO/STOP (которые теперь красные), чтобы подключиться.

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

Изменения в вашу ветку

Наведите указатель мыши на слово Changes и нажмите знак плюса, чтобы подготовить все измененные файлы. Это должно выглядеть так:

Или выберите каждый файл, который вы хотите изменить по отдельности. Staged Changes — это изменения, которые вы собираетесь отправить в коммит, а затем в Pull Request. Как только вы это сделаете, они появятся на новой вкладке «Staged Changes»

Нажмите на один из файлов кода, которые вы изменили! Вы увидите всплывающее окно сравнения исходного файла с новым файлом. Здесь вы можете видеть, строка за строкой, каждое сделанное вами изменение. Красные линии — это строки, которые вы удалили или изменили, а зеленые — это строки, которые вы добавили или обновили. Вы даже можете включить или отключить отдельные строки с помощью меню More Actions (...) в правом верхнем углу.

Теперь, когда вы подготовили свои изменения, вы готовы сделать коммит. В верхней части панели вы увидите раздел Message «Сообщение». Введите имя, описывающее ваши изменения в коммите и описание, если необходимо. Будьте лаконичны! По вашему коммиту должно быть понятно какие изменения оно совершает.

Убедитесь, что вы проверили новую ветку, созданную ранее, и нажмите на галочку! Это сделает ваш коммит и добавит его в вашу ветку. Это должно выглядеть так:

Ну вот! Вы успешно внесли изменения(commit) в свою ветку(branch). Он все еще «неопубликован» и находится только на вашем локальном компьютере, на что указывает значок маленького облака и стрелки в левом нижнем углу.

Публикация на GitHub

Щелкните значок GitHub на левой боковой панели, выглядящий как кошка в кругу. Теперь вам нужно щелкнуть знак +, который появляется в левом верхнем углу, например:

Затем выберите верхний репозиторий (upstream repo) и нацельтесь на главную ветку(master branch). Вы сможете выбрать название вашего PR. Расширение сделает ваш PR с выбранным вами заголовком и описанием по умолчанию. ПЕРЕД ОТПРАВКОЙ: убедитесь, что вы правильно создали PR и следовали шаблону описания.

Примечание к журналам изменений (ChangeLogs). Журналы изменений должны быть ориентированы на игрока, то есть они должны быть понятными и применимыми к обычному пользователю, не знакомому с кодингом. Будьте как можно более проще,

Исправление(fix): Исправлена ошибка с X, когда вы Y
Фича(tweak): усилен X, чтобы наносить Y больше урона.

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

tweak: добавлен флаг NO_DROP к элементу X.
tweak: рефакторинг ДНК, чтобы CPU лучше работал

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

если все пойдет хорошо, ваш PR должен выглядеть так:

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

Учимся кодить

Теперь, когда всё настроено, осталось сделать последний штрих. Изучить логику и код. Ну ладно, не совсем последний штрих. Не бойся, хоть это одна из сложных вещей, есть масса гайдов по Dream Maker, а также кодеры, которые вам помогут! Главное правило изучение - не просите делать всё за вас, а то вы так ничего не изучите. Всё дается не сразу и поэтому стоит набраться терпения и сил. Кодерами не рождаются, ими становятся, пересилив себя ради создания хороших вещей!

Переведенный гайд DM Reference TG STYLE TG STANDARDS

СТОЯТЬ! Если ты только начинаешь и уверен что готов двигаться дальше, то можешь ознакомиться с инструкциями ниже по настройке твоих IDE и дополнительной информацией.

Настройка и использование Github Desktop

Заходим на: https://desktop.github.com/
Скачиваем Github Desktop для своей системы.
Дожидаемся окончания установки!
Следуем шагам для регистрации/логина на GitHub..

Ответвление [Fork]

Читаем данный гайд по ответвлению.

Выпадающее меню

Создание локального репозитория

Открываем Github Desktop
Выбираем "File", "Clone repository.."
Выбираем ваш ответвленный Paradise репозиторий
Выбираем локальный путь куда будет клонирован репозиторий
Нажмите Clone и дождитесь окончания
Теперь у вас есть локальный репозиторий на вашем устройстве

Обновление вашего репозитория

Перед тем как начать работу, вы должно обновить ваш master
Откройте Github Desktop и выберите ваш репозиторий
Нажмите на Current Branch в верхней части экрана
Выберите ваш master, для нашего билда это master220
Кликните внизу на Choose a branch to merge into master220
Найдите upstream/master branch и выберите его.
Нажмите на Merge upstream/master into master

Branch в GitHub Desktop

Ответвляем от репозитория [Branch]

Branch-ветвление вашего репозитория очень важно для организации ваших коммитов (изменений), у вас должна быть отдельная ветка для каждого несвязанного изменения кода (например, если вы хотите создать несколько новых спрайтов для одного элемента и изменить свойства другого, они должны быть в отдельных ветках). Запросы на слияние (Pull Request) работают с ветками (Branch), а не с коммитами, это позволит вам создавать отдельные запросы на слияние для каждого изменения. Это упростит весь процесс и избавит всех от головной боли...
Откройте Github Desktop и выберите ваш репозиторий
Нажмите на Current Branch в верхней части экрана
В выпадающем меню нажмите на New Branch
Задайте ему название зависимое от ваших изменений и нажмите Create branch

Переключение между branch-ветвями

Откройте Github Desktop и выберите ваш репозиторий
Нажмите на выпадающее меню Current branch и выберите branch-ветку на который хотите переключиться.
If you have open changes then it might fail. Either stash, commit or discard the open changes and try again. Если у вас есть изменения, это может привести к ошибке. Вы можете их зафиксировать, оставить в предыдущей ветке, отменить изменения и повторить попытку.

Внесение изменения

Делаем Commit-изменение

Коммит — это подтвержденное изменение файлов в вашем репозитории, именно так вы постоянно вносите изменения в файлы в вашем репозитории, поэтому старайтесь не вносить коммит, не убедившись, что он работает (хотя последующие коммиты могут это исправить).
Как и было ранее сказано, вы должны использовать разные версии веток-branch'ей для внесения ваших commit-изменений. Не вносите изменение в ваш master. Он должен оставаться чистым, чтобы вы могли использовать его для создания последующих веток и откатов при нужде.
Чтобы внести свои изменения-commit'ы, вам нужно отредактировать файлы с помощью встроенных инструментов редактирования BYOND или любого другого инструмента редактирования, такого как Visual Studio Code (Как его установить?), который рекомендуем для разработки. Обязательно соблюдайте стандарты кодирования при внесении изменений!
Откройте Github Desktop и выберите ваш репозиторий
Повторно проверьте внесенные вами изменения.
Назовите внесенные изменения.
Опционально, опишите внесенные вами изменения.
Нажмите Commit to "BRANCH_NAME"
Ваши изменения внеслись в вашу ветку, вы можете повторно увидеть их во вкладке History

Делаем Pull Request (ПР)

Открываем Github Desktop и выбираем ваш репозиторий
Нажимаем на Public branch
Переходим на ваш GitHub репозиторий, к примеру: https://github.com/NAME/Paradise
Нажимаем Pull Request на самом верху
Заполняем форму с изменениями, после чего создает Pull Request.
You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
Готово! Во многих случаях в ваших изменениях могут обнаружиться ошибки, на которые указали другие участники, либо же неудачные конфликты слияния или другие вещи, которые потребуют от вас пересмотра вашего запроса на включение.
Не забудьте убедиться что у вас всё верно и постарайтесь получить одобрение от других участников разработки.
Теперь вам необходимо ожидать внесения ваших изменений в родительский репозиторий.

Setting up & Using TortoiseGit

Настройка на английском. Для новичков рекомендуем по прежнему использовать Github Desktop

Go here: http://code.google.com/p/tortoisegit/wiki/Download
Download the right TortoiseGit for your system.
When installing, click OpenSSH rather than TortoisePLink
Finish installing.
RESTART YOUR COMPUTER THIS IS NOT A DRILL.

Forking Code

See this

Downloading the Code

Find a place you don't mind the code sitting.
Right click and choose Git Clone...
The URL field should be filled with the URL of your Fork. If not, paste it in.
Click Next and watch flying tortoises bring you your code.

Setting up TortoiseGit

Right click on the folder that was created (usually called Paradise), and go to TortoiseGit and then click on Settings.
Click on Remote under Git.
There should be one thing on the list of remotes, with the name: origin.
You're now adding the main repository as a source you can pull updates from.
In the Remote box type in upstream.
In the URL: box put: https://github.com/ss220-space/Paradise.git
Click Add New/Save.
Click Ok.
Almost done!

Updating your Repository

Updating your repo with the master should be done before trying anything.
Right-click the folder your repo is in and select TortoiseGit then Pull.
Click the radial button next to Remote and make sure upstream (or whatever you called it) is selected next to it.
The remote branch should be set to master.
Then click Ok. This will pull the latest changes from the master repo.

Making a Branch

Branching your repo is very important for organising your commits, you should have a different branch for each unrelated code change (e.g. if you wanted to make some new sprites for one item and change the properties of another these should be in seperate branches), as Pull requests work off branches rather than commits this will allow you to make a seperate Pull Request per change. Doing this streamlines the whole process and will save everyone a bunch of headaches.

Right-click in your working folder. Then choose TortoiseGit, and Create Branch...
Type in your new branch name
(Optional) Tick Switch to new branch
Press Okay and your new branch is created

Switching between Branches

Right-click in your working folder. Then choose TortoiseGit, and Switch/Checkout...
Choose your Branch then press Okay

Making a Commit

A commit is confirmed change of the files in your repo, it's how you make changes permanently to the files in your repo, so try not to commit without making sure it works (though subsequent commits can fix it).
As said before, you should use different branches to separate your commits/changes. Don't commit to master. It should be clean, so you can fall back on it if needed.
To make your commits, you need to edit the files using BYOND's inbuilt editing tools. Make sure to follow coding standards when making your changes! When you're finished, right click the folder you're working with and choose Git Commit -> "[Your Branch Name]" (Example: Git Commit -> "My_First_Branch")
You can then select only the files you want to be committed by ticking or unticking them. You should also write a detailed commit summary, detailing what happened in that commit.
Click Ok and the commit will be committed to your local repo!

Making a Pull Request

Right-click in your working folder. Then choose TortoiseGit, and Push...
Set Local and Remote to the name of the branch you committed before. (e.g. My_First_Branch)
Under Destination, set Remote: to origin.
Click Ok. This'll upload your changes to your remote repo (the one on GitHub).
Head to your GitHub repo e.g https://github.com/NAME/Paradise
Click Pull Request at the top right.
Fill out a summary and then create the pull request.
You're done! In many cases there will be issues pointed out by other contributors, unfortunate merge conflicts, and other things that will require you to revisit your pull request.
Optionally, view Clean Commits for a guide on cleaner commit logs, cleaner commits help maintainers review!

Clean commits / Squashing commits(Optional)

Your commit logs are filthy, full of one or two line commits that fix an error that makes you look bad, and the commit is called "Whoops" or "oops"
Navigate to your local version of the branch
Ensure it is up to date with the remote
Go to Show log
Select all the commits associated with this change or PR
Right click and choose Combine to one commit
This will open up the standard commit interface for TortoiseGit, with the commit logs of the selected commits merged together
Perform the normal routine for a commit
Go to push your branch to the remote branch
Ensure Force Overwrite Existing Branch (may discard changes) is selected to make sure the PR/Remote updates to contain just this squashed commit

Как делать предложения правок на GutHub

Файл:GitHub как делать ревью 1.png Файл:GitHub как делать ревью 2.png

Учимся использовать TGUI

Если вы все еще новичок, рекомендуется больше узнать о DM, прежде чем переходить к TGUI. Все наши пользовательские интерфейсы (кроме элементов OOC, таких как панели администратора) сделаны с использованием TGUI или должны быть преобразованы в TGUI в какой-то момент в будущем. (Вот куда это ведет!)

TGUI использует InfernoJS (на основе reactJS), который является расширением для javascript. Учиться может быть сложно, потому что это совершенно другой язык, но не бойтесь! Есть много руководств, которым вы можете следовать.

Guides

TGUI прост, но его трудно понять тому, кто с ним не знаком. ПРОЧИТАЙТЕ ЭТИ РУКОВОДСТВА. И да. Они на английском.

Обязательно прочитайте их по порядку

A re-introduction to JavaScript
Guide to using ReactJS <- На самом деле мы не используем react, но полезно для изучения
Brief rundown of InfernoJS
TGUI Tutorials and Examples

Как внести свой вклад?
Общее	Руководство по разработке
Сервер	Настройка базы данных, Запуск локального сервера
Код	Структура кода SS13, SS13 для опытных программистов, Форматирование текста, Как делать перевод игры
Маппинг	Руководство по маппингу
Спрайтинг	Руководство по спрайтингу
Вики	Руководство по редактированию вики