Участник:Richard Jones/Git/Github Desktop

Материал из Tau Ceti Station Wiki
Перейти к навигации Перейти к поиску

Решили внести вклад в наш билд? Отлично, вы в правильном месте! В этой статье кратко пройдемся по полному алгоритму действий, который вам потребуется сделать - от начала и до конца. Пристегните ремни, и мы начинаем.

Что за зверь?

GitHub — это сайт и сервис для хранения и совместной работы над кодом. На данный момент это наиболее популярный в сообществе игры хостинг репозиториев (или просто "репо") - папок для проектов на GitHub.

Вот некоторые основные репозитории игры:

Зайдите на наш репозиторий. В разделе "Issues" вы найдете баги и предложения. Для того чтобы создать issue (ишью), вам необходимо нажать на кнопу "New issue". То, как должны оформляться баги, достаточно подробно расписано при создании самого ишью. Предложения же оформляются в свободной форме. Тут могут быть как просьбы добавить что-либо в игру, так и предложения на портирование каких-либо фич с других серверов. Хорошим тоном будет в начале заголовка добавить [Proporsal].

В разделе "Pull requests" вы найдете так называемые ПР-ы. Pull request в переводе значит - "запрос на изменения", что в свою очередь означает - предложить какие-то коммиты (изменения) из форка в основной репозиторий. Чтобы внести свои изменения в билд, вам потребуется создать свой ПР - мы еще коснемся этого позже в данной статье.

За исключением некоторых случаев, процесс работы выглядит примерно следующим образом:

  1. Есть центральный репозиторий, с которым все синхронизируются, и в который через PR (пулл-запросы) кидаются изменения.
  2. Каждый участвующий разработчик делает свой собственный форк (ответвление от основного репозитория, по сути собственная удаленная копия репозитория), клонирует свой форк на локальную машину для работы, делает вещи.
  3. Когда что-то готово, изменения сначала коммитятся (фиксируются) в свой форк, после с форка создается пулл-запрос на принятие изменений в основной репозиторий.
  4. PR проходит ревью у мэйнтейнеров проекта (сопровождающих разработчиков), по необходимости вносятся изменения/исправления, и далее, либо принимается, либо отклоняется.

Испугались? На практике все не так сложно, давайте приступим.

Инструменты для работы

Если вы еще не имеете Гитхаб аккаунта, нужно его создать - переходим на https://github.com/join, подтверждаем email. Внимание! Github может использовать вашу почту регистрации для подписи всех ваших изменений. Почта будет видна всем при работе с репозиторием. Учтите это, и либо подойдите грамотно к выбору ящика, либо согласитесь когда Github предложит подписывать коммиты alias-адресом, вместо вашей почты.

Помимо этого, нужно скачать Git и GitHub Desktop.

  • Git - да, консольный гит тоже лучше скачать, без него никуда.
  • Github Desktop - В целом, вы можете использовать любой Git-клиент, которым вы уже умеете пользоваться (Например, GitKraken), но этот гайд будет написан для GitHub Desktop, и автор советует использовать именно его. Если вы безумец вам больше по душе консольный гит - вы можете прочитать этот гайд. Не забудьте залогиниться!

Делаем форк

Войдя в приложение, нам потребуется сделать так называемый форк. Форк будет вашей собственной копией нашего репозитория, с которой вы можете делать все, что пожелаете! Просто нажмите эту кнопку на https://github.com/TauCetiStation/TauCetiClassic:

How to fork.png

Как только вы его сделаете, у вас должно появиться что-то подобное в вашем базовом профиле на GitHub.:

How to fork2.png

Отлично! Итак, я надеюсь, вы уже скачали Github Desktop? Следующая часть будет простой: нажмите эту удобную кнопку под “Code” прямо здесь:

How to fork3.png

Вы увидите экран, который выглядит примерно так. Просто убедитесь, что у вас есть чистая папка, в которую Git сможет клонировать себя, и нажмите “Clone”:

How to fork4.png

Итак, на следующем экране вам нужно нажать “Contribute to the parent project”. Это важно, потому что это немного облегчит вашу жизнь на последующих этапах (На этапе Пул Реквеста):

How to fork5.png

Круто, теперь у вас есть копия нашего билда!

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

Однако, прежде чем делать какие-либо изменения, вам нужно сделать одну важную вещь:

How to fork6.png

Создать новую ветку! Это супер важно, потому что нам нужно, чтобы главная “master” ветка на вашем форке была как можно более "чистой", без ваших изменений. Для каждого отдельного проекта, над которым вы работаете и для которого отправляете запрос на обновление, вы создадите отдельную ветку. Не стесняйтесь называть ее как хотите! В конце концов, это ваша ветка.

How to fork7.png

Вы также можете увидеть экран с надписью “base it off the current branch” или “base it off the upstream/master”. Это зависит от того, чего вы хотите, но если вы хотите начать новый ПР с чистого листа, всегда нажимайте “base it off the upstream/master”.

How to fork8.png

Вот, как все должно выглядеть. Вы отлично справляетесь, так держать!

Устанавливаем хуки

Этот шаг очень важен!

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

Во-первых, в корневом каталоге вашего репозитория перейдите в /tools/_git-hooks и запустите _install.sh. Это автоматически настроит ваши Git-хуки, что избавит вас от многих трудностей. Этот хук будет "объединять" ваши изменения, когда вы редактируете карты. Удостоверьтесь, также, что у вас стоит Java, она нужна для хуков.

Пишем лучшую фичу в истории билда

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

Также, перед тем, как делать изменения, нужно подтянуть обновления с нашего репозитория . Сделать это не сложно! Переходим в меню "Branch" и нажимаем "Update from upstream/master":

How to fork9.png

Нужно будет проделать то же самое перед тем, как создавать ПР. Если вы не следуете этому руководству с самого начала, проверьте, что в Repository -> "Repositoty settings...", в меню "Fork behavior" у вас стоит "То contribute to the parent repository" Это важно для актуальности ваших веток.

Отправляем Commit

Пришло время отправлять изменения на главный репозиторий. Зайдите обратно в GitHub Desktop и проверьте, что в файлах нет лишних изменений, которые вы не хотите отправлять. Если вы хотите избавиться от чего-то - просто щелкните правой кнопкой мыши на файл, который хотите удалить, и нажмите “Discard changes”.

How to commit1.png

Допустим, я доволен тем, что сделал - что тогда? Меню коммита! Постарайтесь давать вашим коммитам адекватные названия, в формате "Removes clown" или "Tweaks the dorm room". Имена в формате fuck, shit, changes, qwerty, 12345 и т.д. крайне не приветствуются и считаются признаком плохого тона.

How to commit2.png

Отлично. Теперь нажмем “Commit to (здесь название вашей ветки)”. Если там написано “Commit to master/main”, не нажимайте эту кнопку, потому что вы испортите свою главную ветку вашего репозитория.

Поздравляю, вы “коммитнули” свои изменения! Что делать, если вам что-то в них не понравилось, и вы поняли, что допустили опечатку, или просто захотите вернуться? Вы всегда можете просто сделать другие изменения и снова сделать коммит, но вы также можете перейти на вкладку "История" и нажать эту кнопку:

How to commit3.png

“Undo commit” просто отменит ваш коммит, и тогда вы сможете внести любые новые изменения, а затем повторно сделать коммит. Это одно из преимуществ Git: у него мощная система управления версиями, которую вы можете легко использовать для перехода от одной точки во времени работы к другой.

Создаем Pull Request

PR (Pull request) - это запрос на слияние предложенных вами изменений в основной репозиторий. Базой для PR-а является branch (ветка) с вашими изменениями.

Если вы довольны тем, что получается, и готовы отправлять это в основной билд на ревью, то обратите внимание на эти кнопки:

How to commit4.png

Любой из этих вариантов сработает, и ваша ветка будет загружена на удаленный сервер (github.com). Вот что отобразится далее:

How to commit5.png

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

How to commit6.png

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

Правильно пишем чейнджлог

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

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

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

  • - bugfix: тут описываются различные фиксы;
  • - rscadd: в эту группу нужно вносить добавление нового функционала или фичь;
  • - rscdel: откаты фичь, удаление старого или ненужного и так далее;
  • - image: всё что касается визуальной составляющей уйдёт в эту группу;
  • - sound: звуки и всё что с ними связано будут тут;
  • - spellcheck: исправления/изменения в тексте;
  • - tweak: изменения влияющие на игровой процесс, но, как правило, базирующиеся на существующем и являющиеся, в общем масштабе, незначительными (настройки чего-то или мелкофичи);
  • - balance: затрагивая игровой баланс смело пишите сюда;
  • - map: изменения на карте;
  • - performance: всё что влияет на производительность игры или работы билда в целом, и прочее;
  • - experiment: в данном разделе нужно описывать изменения, вероятность отката которых, вы не исключаете;
  • - ru: изменения, касающиеся перевода; (вместо ru также можно использовать localization)

Стоит оговорить, что текста в чейнджлоге должно быть немного, но и информативность должна быть сохранена по-максимуму. Если вы уверены, что не уложитесь в понятие краткость, то вы можете воспользоваться маркером [link] , который нужно добавить к конкретной группе. Маркер даст указание обработчику в автоматическом порядке дописать к чейнджлогу гипер-ссылку ведущую на ваш ПР, в котором вы можете спокойно разгуляться с описанием. Как это должно выглядеть на практике можно увидеть в далее приложенном примере.

Важно: [link] - это всего лишь маркер для обработчика . В саму метку НИЧЕГО помещать не надо, ссылка получается АВТОМАТИЧЕСКИ обработчиком в процессе генерации чейнджлога.

На этом всё. Нажимаем "Create pull request". Готово! После создания ПРа :cl: заменится на эмодзи.

Пример 

Текст с описанием вашего ПРа.
:cl:
- bugfix: Фикс невозможности сделать какое-либо действие.
- rscadd[link]: Добавлена куча ранее невиданных фич, описание каждой выльется во второй том произведения "Мёртвые души". (Тут, в игре, будет добавлено "- подробнее -", которое будет являться гипер-ссылкой.)

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

How to commit7.png

Нажмите “Create Pull Request” и дождитесь реакции браузера.

У вас получилось! Вы создали ПР на Гитхабе!

Взаимодействие с командой разработки

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

За билд в целом и код в частности отвечает команда мейнтейнеров (от слова "maintain"). Вы можете распознать их в дискорде по плашке Build Maintainer. У вас может быть интересная фича, но плохой код. Или хороший код, но сомнительная фича. Такие случаи разрешаются ими.

За спрайты отвечают люди с плашкой Sprites Department. Эта группа лиц выносит финальное и окончательное решение в адрес всего, что связано со спрайтами. Важно отметить, что на текущий момент мы стараемся придерживаться консистентности в области добавляемого графического контента, поэтому их слово в данном вопросе суть решающее. Рекомендуется консультироваться с ними в канале #sprites.

Когда же мои изменения попадут в билд?

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

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

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

В принципе, если вы считайте, что всё сделали правильно, то можете отстоять свою позицию в споре. Если ревьюер действительно не прав, то вашу точку зрения поддержат другие. Так или иначе, все нерешённые косяки придётся править вам (ну или тому, кто согласится вам помочь).

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

Спасите! У меня возникли конфликты!

Речь пойдет не о конфликтах с мейнтейнерами (надеемся, что их у вас возникать не будет), а с конфликтами изменений кода. Например, вы работаете над новым видом хлеба - и пока вы работали, кто-то успел добавить в билд бургер. Все бы ничего, но ваши изменения пересекаются в нескольких файлах, из-за чего возникает конфликт - гитхаб хочет, чтобы у вас была самая последняя версия билда!

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

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

Конечно, редко бывают более сложные случае - для не решаемых хуками конфликта карты нужно, чтобы два маппера редактировали один и тот же тайл карты, а для не решаемых конфликтов спрайтов нужно, чтобы два стейта редактировались одновременно. Шанс этого небольшой, но если это все-таки случилось - у нас в дискорде есть канал ⁠#howto-code, где вам помогут с любыми вопросами касательно кода.

Список документации

Здесь мы кратко прошлись по работе с гитхабом, если вы хотите достигнуть более широкого понимания - рекомендуем почитать что-то из данного списка:

Источник — https://wiki.taucetistation.org/index.php?title=Участник:Richard_Jones/Git/Github_Desktop&oldid=31095