Skip to content

Latest commit

 

History

History
96 lines (61 loc) · 19.3 KB

CONTRIBUTING.md

File metadata and controls

96 lines (61 loc) · 19.3 KB

Вклад (CONTRIBUTING)

Вступление

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

Работа с гитом

Весьма подробный гайд по работе с технологией git на примере консоли, описан на нашей основной Вики: http://tauceti.ru/wiki/Git/Git-console. Прочитайте на досуге.

Готовая помощь

Перед началом работы с проектом зайдите в папку tools/_git-hooks и прочитайте README файл. После этого запуститите install скрипт под вашу систему. Так вы подключите к своему локальному репозиторю скрипты, которые облегчат вам вашу жизнь котрибьютера в будущем.

Также в папке tools/_git-helpers вы можете найти скрипты, которые исполняют комплексную логику. Всё описание можно найти в README.

Рекомендации по гиту

В интернете очень много статей на эту тему. Если вы новичок, то прочитайте одну-две. Обратите внимание на такие темы, как: разрешение конфликтов (Merge Conflicts), Git Workflows, атомарные коммиты.

Коммит

Оформление

Давайте своим коммитам адекватные названия. Не обязательно помещать в них детальное описание вносимых изменений (хотя и желательно), но имена в формате fuck, shit, changes, qwerty, 12345 и т.д. крайне не приветствуются и считаются признаком плохого тона.

Если в своём коммите вы фиксите/закрываете какой-то ишью, не давайте распознаваемые гитхабом названия fixes, closes и т.д. Использовать их нужно, но уже в основном теле описания ПРа.

Важно!

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

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

Пулл Реквест

Нюансы внесения изменений

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

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

Атомарность

Под атомарностью подразумевается такой принцип, когда ваш ПР содержит только изменения на конкретную тематику. Например, когда вы добавляете новое оружие, ваш ПР не должен содержать рефактор органов мобов. Почему? Потому что одно с другим никак не связано. А если связь и имеется, то явно не до такой степени.

Оформление

Весьма детально оформление ПРов затронуто в статье на Вики.

Название

Название ПРа должно хотя бы частично, но передавать его суть. Также, как и в случае с коммитами, не давайте такие названия, в которых гитхаб будет распознавать ключевые слова (fixes, closes и т.д.).

Если вы создали ПР, но он всё ещё незакончен и вы над ним работаете, добавьте в начало названия [WIP]. В случае если по каким-то причинам вы в приниципе не хотите, чтобы ПР в текущем виде был смержен добавьте [DNM]. Пример: [WIP] Добавлена убер фича

Основное тело

Максимально, на сколько вы способны, опишите внесённые изменения. Желательно не оставить без внимания даже мельчайшие нюансы. И обратите внимание на читабельность своего текста. Простыня текста без банального разделения на абзац - это очень плохо.

Как уже говорилось чуть выше, именно в основном теле вы должны использовать ключевые для гитхаба слова типа fixes, closes и т.д. Подробнее тут https://help.github.com/articles/closing-issues-via-commit-messages/.

Таким образом вы значительно облегчите работу ревьюерам и ускорите процесс мержа.

Чейнджлог

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

Переоткрытие, почему так делать нельзя

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

Поэтому проявите сдержанность и не делайте поспешных решений. Нерешаемые ситуации сами собой не создаются, их создают резкие и необдуманные действия. Сначала ищите решение в интернете, затем идите в #rnd или #howto-code каналы нашего дискорда. И там, и там есть люди, которых можно слапнуть и которые смогут что-то вам подсказать (@Codehelp-slap или @Build Maintainer). Не создавайте сложности себе и другим.

Прочее, но не менее важное

Code Convention

Очень важно, писать код не только рабочий, но и качественный. Минимизируйте количество анти-паттернов в своём коде. Организуйте продуманную архитектуру. Короче сделайте свой код красивым, читабельным и легко расширяемым. Или хотя бы попытайтесь. Но самое важное, прочитайте и соблюдайте Code Convention. Если вы будете им явно пренебрегать, то не ожидайте, что ваш ПР будет в ближайшее время смержен.

Применение анти-паттерна Copy-Paste

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

Legacy Code

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

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

Но!

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

Согласование

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

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

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

Изменения, связанные с картой

Перед тем как делать изменения связанные с картой (файлы с dmm расширением) зайдите в папку tools/dmm-merge-tool и прочитайте README файл. Резюмируя там написанное, вам крайне рекомендуется зайти в tools/_git-hooks папку и запустить install скрипт. После этого вы можете спокойно изменять и коммититить изменения без лишних действий. В противном случае вам придёться проделывать всё то, что было описано в данном параграфе.

Disclaimer

Для работы инструмента требуется установленная Java. Если у вас что-то не взлетает, то ищите в этом направлении.

Если вы только начали...

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

Не поймите нас неправильно. Будет очень здорово, если вы попробуете и у вас сразу всё будет получаться. Но реальность такова, что даже такой простой язык как BYOND требует практики и опыта. Как минимум нужно некоторое время, чтобы освоиться с билдом и тем, что и где в нём находится.

Начните с чего-нибудь небольшого. Фиксы, мелкие фичи или порт этих ж фич и фиксов с других билдов. Даже если вам кажется, что это не нужно и кажется вам неинтересным. Это не так, бесполезных изменений не бывает. А в сам процесс программирования, если это вам действительно интересно, вы постепенно втянетесь. Так, поступательно, вы наберёте опыт и сами поймёте, что готовы. И тогда у вас само начнёт получаться делать всё больше и лучше.