Guide to Contribution

В разработке…

Данная статья помечена как неоконченная. Это означает, что статья находится на доработке, поэтому является неверной или неактуальной. Вы можете помочь проекту Onyx и сообществу SS13 в целом — зайдите на наш Портал сообщества.

Что может быть интереснее того, чтобы играть в компьютерную игру? Правильно! Менять мир игры и наблюдать, как глупые ньюфаги превозмогают. Хотите знать, как делают игры? Отлично, в этой статье мы и разберем все, что касается разработки билда Space Station 13, помимо самого написания кода.

Зачем все это? Давайте просто писать код!

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

Наверное, ты уже видел один из реальных билдов Space Station 13? При достаточной внимательности, ты даже мог там разглядеть кнопку "Download ZIP". Давай пойдем по наивному пути и попробуем его скачать.

Скачав и разархивировав архив, ты получил папку с полной копией того билда, который, скорее всего, прямо сейчас работает на сервере. Что мы видим в типичной папочке с билдом? Рассмотрим на примере сборки Baystation12:

• название_билда.dme (Dream Maker Environment) - самый главный файл исходных кодов игры. Он хранит в себе список всех файлов с кодом, которые будут скомпилированы в дистрибутив игры. Все просто: добавили новый файл - добавили его путь в .dme; не хотите чтобы какой-то файл компилировался в сборку - удалите его отсюда. Это файл можно открыть бьондовским Dream Maker'ом, в котором можно добавлять/исключать файлы из сборки с помощью дерева файлов в его интерфейсе слева.
• название_билда.dmb (Dream Maker Build) - скомпилированная версия сборки. Dream Maker собирает все исходные файлы с кодом, которые указаны в .dme файле вместе, компилирует их и отдает этот .dmb файл, который можно загрузить в Dream Daemon, чтобы запустить сервер.
• code, icons, interface, fonts, maps, sound - обычные папки, в которых, внезапно, лежат исходные коды, иконки, файлы интерфейса, шрифты, карты и звуки соответственно. Здесь все легко.
• config - важная папка с конфигами сервера. Перед первым запуском локальной сборки, убедись что скопировал файлы из подпапки examples в корень папки config и все правильно настроил.
• html - различные html-формы, которые используются для описания расположения элементов интерфейса во всяких консолях, панельках, а также вспомогательные элементы.
• tools - скрипты и программы, в основном, на нормальных языках программирования, которые могут понадобится при разработке и запуске сервера. Например, здесь может быть программа, которая переводит музыку в формате midi в ноты для пианино.
• sql - конфигурационные файлы для запуска Базы Данных под сервер.

Хорошо, мы разобрались с тем, что тут лежит. Допустим, ты нашел какой-то файлик с кодом и решил в нем что-то поменять, скажем, урон у дубинки СБ - одно число. Скомпилировал билд, запустил у себя локальную версию - все хорошо. Далее ты хочешь сделать так, чтобы эти изменения попали на сервер - как ты их будешь передавать?

Можно, конечно, взять этот файлик, отправить владельцу сборки на GitHub'e, чтобы он полностью заменил файл. Также, например, можно попросить его заменить все самому в конкретной строчке, но чем больше будет количество изменений и людей, которые их вносят - тем сложнее будет со всем эти справляться. Тут приходит на помощь Git.

Тут важно отличать две вещи - Git и GitHub. Первое - это обычная маленькая программа для сохранения истории изменений кода, а второе - это интернет-портал, который позволяет хранить у себя твои исходные коды.

Что делает Git? По сути, он сравнивает исходную версию всех файлов до изменений с тем, что получилось в итоге и создает список изменений - diff (от слова difference). Далее он помогает зафиксировать эти изменения и сохранить со своим описанием в специальном архиве изменений, в подпапке .git. Зафиксировав изменения, их можно будет откатывать, восстанавливать, сливать и делать с ними прочие непотребства, не беспокоясь о том, что твоя работа куда-то пропадет - вся история изменений останется в архиве и ее всегда можно будет восстановить. Более того, любой другой человек может прийти и посмотреть всю историю работы со сборкой. И это еще не все, git позволяет синхронизировать твой локальный архив изменений с другими архивами, которые расположены у других разработчиков на компьютерах, или, например, на GitHub'e.

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

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

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

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

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

Берем в руки Git и готовимся к поступлению в Академию Магов

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

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

Для совсем новичков, остановимся на примере SourceTree - это самый простой способ сделать свой первый коммит. Скачивать репозиторий zip-архивом не нужно, все скачается автоматически.

Итак, заходим на официальный сайт [SourceTree https://www.sourcetreeapp.com/], качаем версию под свою ОС и устанавливаем. Сам Git входит в сборку SourceTree и будет установлен автоматически - отдельно его ставить не нужно. После установки, нужно будет зарегистрироваться у разработчика, на сайте Attlasian. Этот аккаунт может тебе еще пригодится, если ты будешь работать с репозиторием, расположенным на BitBucket, а не на GitHib'е.

Запустив SourceTree, щелкаем Файл/Клонировать. Указываем сайт репозитория (например, https://github.com/Rampoch/Chaotic-Onyx), путь, где мы будем хранить репозиторий локально и название для отображения в интерфейсе программы. Жмем кнопку клонировать. В выбранной папочке создастся новый репозиторий - точная копия репозитория, который хранится на сервере GitHub. Теперь мы можем тут что-то поменять и залить изменения на оригинальный репозиторий сервера.

Интерфейс SourceTree

Интерфейс SourceTree

Что у нас есть в интерфейсе SourceTree?

• Вкладки. Каждая вкладка - отдельный локальный репозиторий. То есть все, что мы видим на этой вкладке - касается конкретного репозитория, который мы создали.
• Нижние вкладки. Это разные панели с полезной информацией о состоянии репозитория.
  • Состояние файлов - все изменения, которые были внесены в файлы, которые содержаться в репозитории, но еще не зафиксированы. Если залезть сейчас внутрь папки репозитория и поменять любой файл, то изменения появятся в этой закладке.
  • Журнал/История - история изменений, все коммиты по всем отслеживаемым веткам. На скриншоте видно очень много веток - потому что это Baystation12, там каждый разработчик создает свою ветку, а потом они мержатся в основную. Каждая строчка - это отдельный коммит, со своим автором, номером, датой и описанием. Выбрав конкретный коммит, снизу можно посмотреть список измененных файлов и конкретные изменения каждого файла. Также там есть полное описание коммита, которое могло не поместится в строчке выше и дополнительная информация.
• Левая панель. Содержит список всех веток в репозитории, внешних веток, меток и спрятанных изменений. Ветки - это просто наборы коммитов, разные ветки истории изменений, по сути. То есть начиная с некоторого состояния репозитория, например, 12 марта, два разработчика начали параллельно вносить какие-то изменения. Удобно, если каждый будет создавать новые коммиты в своей отдельной ветке, тогда их изменения не будут перемешиваться, а когда они закончат - можно будет удобно слить их в одну основную ветку.
• Верхняя панель. Главные кнопки для работы с репозиторием.
  • Закоммитить - создать новый коммит. Эта кнопка соберет все изменения, которые были внесены, спросит описание изменений и создаст новый коммит, который сразу окажется в локальном репозитории. Пока коммит хранится только локально у тебя, можно его изменять и даже удалять, но как только ты его отправишь в основной репозиторий на сервере GitHub, удалить его уже будет нельзя. Так что не стоит сразу пушить все свои коммиты на сервер, 10 раз подумай, не сохранил ли ты случайно какой-нибудь мусор, или, хуже, личную информацию, которую не хотел бы раскрывать.
  • Отправить - отправить все коммиты, которые были сохранены локально в удаленный репозиторий, например, в репозиторий сервера на GitHub. В диалоге можно будет выбрать какую конкретно ветку отправить в какую ветку в каком удаленном репозитории, если у тебя там много вариантов.
  • Получить - скачать все коммиты с удаленного сервера к себе в локальный репозиторий. Коммиты переезжают из конкретной удаленной ветки в конкретную локальную ветку. Да, автоматически ничего обновляться не будет, так что перед началом работы над новым коммитом, лучше скачай все изменения из репозитория сервера этой кнопкой.
  • Извлечь - получает только информацию о том, есть ли на сервере новые коммиты. То есть ты увидишь новые коммиты в удаленных ветках, но локальные ветки останутся без изменений.
  • Ветка - создать новую ветку, начиная с текущего коммита.
  • Слияние - сливаем две ветки в одну. Все коммиты из обеих веток будут выстроены в истории по времени, а в конце будет добавлен новый мерж-коммит, в котором можно будет разрешить все конфликты, если они будут. Конфликт - это когда в разных ветках трогали одни и те же строчки одних и тех же файлов. Чтобы решить такой конфликт - надо выбрать какие варианты должны войти в итоговый результат.
  • Спрятать - прячем все текущие изменения под каким-то названием, с возможностью их потом вытащить. Иногда бывает удобнее, чем плодить ветки.
  • Терминал - откроет консольное окно, куда можно будет вбивать сырые команды Git. Иногда бывает полезно, если ты хочешь сделать какую-то сложную штуку, которую либо не завезли в интерфейс, либо ты не знаешь где ее искать.

Твой первый коммит

Интерфейс создания нового коммита в SourceTree

Итак, ты установил SourceTree и создал свой локальный репозиторий, склонированный с оригинального репозитория сервера. Для начала, надо что-то сделать. Допустим, ты поменял пару файлов.

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

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

Создаем Pull Request на GitHub

Отправить свои коммиты напрямую в репозиторий сервера на GitHub'e тебе, скорее всего, не дадут. Для внесения своих изменений в чужие репозитории, на GitHub придумали Pull Request'ы, запросы на забор кода из твоего репозитория. Чтобы создать такой запрос, тебе нужно (1) клонировать исходный репозиторий, создав новую копию под своим аккаунтом на GitHub; (2) внести коммиты с локального репозитория у тебя на компьютере, в этот новый репозиторий на GitHub, под твоим аккаунтом; (3) сделать запрос на забор кода из твоего репозитория GitHub в репозиторий сервера.

Чтобы клонировать репозиторий к себе на аккаунт, нужно нажать кнопку Fork в интерфейсе страницы репозитория на GitHub'e. У тебя в профиле появится новый репозиторий, полная копия основного, в который ты сможешь заливать свои изменения. Обрати внимание, что в него не будут автоматически добавляться изменения из основного репозитория - нужно будет обновлять руками. Чтобы добавить коммиты, которые уже есть в локальной истории у тебя на компьютере, в этот репозиторий, нужно в SourceTree добавить новый внешний репозиторий и пушить в одну из его веток. Лучше для каждого нового набора изменений создавать на внешнем репозитории новую ветку, чтобы не мешать тематически разные изменения и создавать для них отдельные Pull Request'ы.

Ну и наконец, чтобы сделать сам Pull Request, идем в основной репозиторий сервера, нажимаем соответствующую кнопку. Выбираем основную ветку репозитория сервера (в нее будем заливать изменения), а для ветки из которой нужно забрать коммиты, указываем соответствующую ветку в твоем внешнем репозитории на аккаунте.

Фокусы любого приличного волшебника

Создаем чистые Pull Request'ы

Очень часто у новичков возникают проблемы с тем, чтобы сделать чистый Pull Request, который будет максимально понятным любому, кто на него посмотрит. Простой способ делать правильные PR'ы:

1. Перед тем как ты начал что-либо делать, обнови основную ветку локального репозитория, забрав все новые коммиты из основного репозитория сервера на GitHub'е. Сразу отправь все эти новые коммиты в свой внешний репозиторий на GitHub (ты же еще помнишь, что он не обновляется автоматически?).
2. Создай новую ветку, в верхушке основной ветки локального репозитория. Лучше назови ее как-нибудь так, чтобы было понятно, чем ты собираешься в ней заниматься. Все свои коммиты на эту тему пиши прямо в эту ветку.
3. Если ты закончил и внес все изменения, какие хотел, обязательно скомпилируй билд и проверь на локальном сервере, что все работает так, как должно! Если забивать на этот пункт, то твои ПРы любой адекватный админ будет принимать очень и очень долго.
4. Если у тебя очень много коммитов или у них не достаточно понятное описание - мягко откати все свои коммиты до последнего не-твоего коммита (ПКМ по первому коммиту сверху, который сделал не ты; "сбросить состояние текущей ветку к выбранному коммиту"; режим выбираем мягкий, чтобы сохранить все изменения, сбросив лишь фиксации). Сразу после отката все твои изменения останутся проиндексированными в списке изменений, но коммиты будут сброшены. Создаешь новый красивый коммит с хорошим описанием.
5. Отправляй свои изменения в свой внешний репозиторий, в ветку с таким же названием. Уже в этой ветке откатить ничего не получится, потому что она хранится на GitHub. Но на самом деле, это временная ветка, которая нужна лишь для того, чтобы прикрепить ее к Pull Request'у. Так как все твои изменения всегда будут у тебя на компьютере локально, ты всегда можешь удалить эту ветку и создать заново, чтобы сделать историю коммитов чистой. В этой ветке, желательно, всегда иметь хорошие коммиты, с нормальным описанием, которые логически разбиты на этапы внесения изменений.
6. Создаем сам Pull Request, привязывая к нему нашу ветку с идеальными описаниями коммитов. В описании обязательно стоит описать все изменения, которые были проделаны в ветке, даже если все подробно описано в самих коммитах - отсюда потом удобно будет скопировать изменения, например, в внутриигровой changelog.
7. Если все хорошо, то твой PR просто примут и все, но так бывает очень редко. Скорее всего, у принимающего будут какие-то вопросы и пожелания по изменениям, тогда после того, как ты внесешь изменения, желательно мягко отменить последний коммит локально, пересоздать его с дополнительными изменениями, а потом перезалить внешнюю ветку, чтобы обновить коммиты на GitHub'e. PR должен автоматически подобрать новую ветку (ну или там можно руками выбрать новую ветку), так что его пересоздавать не нужно!