Руководство для кузнецов

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

Обязательно прочтите статью «Установка Habitica локально» для получения важной информации о начале работы, а также «Внесение изменений в сайт Habitica и API с помощью локальной копии», чтобы понять как устроен процесс внесения изменений.

Способы помочь[]

Сайт[]

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

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

Я хочу начать с чего-то малого: Проверьте список ишью на Github, и поищите ишью с меткой good first issue, где вы сможете попросить внести свой вклад.
Я хочу помочь там, где я больше всего нужен: Поищите на Github ишью с метками help wanted, priority: critical и/или priority: important, и спросите можно ли начать над ними работу. Решив баг с меткой priority: critical вы сможете получить Молот победителя критических багов. Поскольку мы работаем над polish the recent frontend overhaul, пул-реквесты относящиеся к ишью с меткой POST-REDESIGN получат ускоренное ревью и contributor credit.
Я хочу писать юнит-тесты и Karma-тесты!: Приветствуем тебя, убийца багов! Ознакомься с разделом «Написание и запуск автоматических тестов» в статье «Внесение изменений в сайт Habitica и API с помощью локальной копии» для получения дополнительной информации.
Я хочу мастерить вещи!: Вот он, наш герой! Следите за списком ишью, потому что сотрудники иногда создают ишью для новых функций, которые были одобрены для реализации. Если вы не можете найти что-то, что вам было бы интересно, то вы можете поискать в списке функций на Trello но крайне важно, чтобы вы сначала попросили выяснить, был ли выбранная вами функция была одобрена сотрудниками. Некоторые предлагаемые функции не подходят для реализации, и пул-реквест, который их реализует, не будет принят.

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

Мобильное приложение для iOS[]

Приложение Habitica для iOS имеет собственную кодовую базу в своем собственном репозитории GitHub на github.com/HabitRPG/habitica-ios. It is open source and contributions are welcome.
Если вы хотите внести свой вклад в приложение для iOS, список ишью содержит список уже запрошенных функций и известных ошибок. Не стесняйтесь просматривать их, чтобы найти то, над чем вы хотели бы поработать. Чтобы избежать дублирования работы, необходимо оставить комментарий по вопросу, над которым вы собираетесь работать. Если вы хотите поработать над функцией, у которой еще нет существующей проблемы, сначала создайте ее, чтобы обсудить детали реализации.

Мобильное приложение для Android[]

Приложение Habitica для Android имеет собственную кодовую базу в своем собственном репозитории GitHub на github.com/HabitRPG/habitica-android. It is open source and contributions are welcome.
Если вы хотите внести свой вклад в приложение для Android, список ишью содержит список уже запрошенных функций и известных ошибок. Не стесняйтесь просматривать их, чтобы найти то, над чем вы хотели бы поработать. Чтобы избежать дублирования работы, необходимо оставить комментарий по вопросу, над которым вы собираетесь работать. Если вы хотите поработать над функцией, у которой еще нет существующей проблемы, сначала создайте ее, чтобы обсудить детали реализации.

BountySource[]

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

Стек технологий сайта[]

Ниже перечислены технологии, которые используются для сайта Habitica. Вы не должны знать все из них, даже большинство из них, чтобы помочь разработке! Некоторые ссылки также включают качественный обучающий материал. Большинство из этих технологий (те, которые имеют '.js' или 'JS' в названии или URL) основаны на языке программирования JavaScript, о котором вы можете узнать здесь.

Сервер[]

Технология	Дополнительная информация
ExpressJS
Node.js	Как начать работу с Node.js nodeschool – очень полезный интерактивный семинар по Node для новичков.
MongoDB	Официальная документация по MongoDB См. также раздел MongoDB ниже, где приведено несколько основных советов.
MongooseJS
monk	Используется для одноразовых скриптов для обновления базы данных ("миграции")
Gulp	Вы можете узнать о нем на странице GitHub Gulp.
Git и Github	Pro Git – уделив немного времени этому ресурсу вы станете чувствовать себя более комфортно при работе с Git. git-it – весёлая и интерактивная часть курса nodeschool поможет понять Git и Github. (Прокрутите вниз для дополнительной информации.)
ESLint	Конфиг Eslint для проектов HabitRPG

Клиент[]

Технология	Дополнительная информация
Bootstrap
Pug (Jade)	Pug (ранее Jade) используется для серверного языка шаблонов, что позволяет внедрять переменные (`res.locals` из Express). Парадигма Pug "significant whitespace" также защищает от распространенных HTML ошибок, например пропуск закрывающих тегов.
SCSS (SASS)
Vue.js	Vue.js представляет для сайта отзывчивый фронтенд. Администраторы Habitica рекомендует использовать эти обучающие ресурсы: https://ru.vuejs.org/v2/guide/ – наиболее важное руководство http://vuejs-templates.github.io/webpack/ и https://vue-loader.vuejs.org/ru/ – полезно для понимания этапов сборки http://router.vuejs.org/en/ – документация по router; не столь важен как остальное и, возможно, он вам не потребуется https://vuex.vuejs.org/ru/guide/ – управление состоянием; прочтите только введение т. к. код Habitica немного отличается

Тестирование[]

Технология	Дополнительная информация
Karma	Запуск юнит-тестов на Karma См. раздел Написание и запуск автоматических тестов.
Mocha
Travis CI	Используется для запуска всех тестов для каждого пулл-реквеста, и отчетах о результатах.

Сервисы[]

Технология	Дополнительная информация
Amplitude	Поставщик услуг аналитики, для расчета engagement и retention
Docker Hub	Хранилище образов релизов Habitica для деплоя
Microsoft Azure	Сервера для облачных вычислений

Reverse-Engineered Requirements Documents[]

В июне 2019 г., студенты из University of Brasília проанализировали Habitica для проекта. Их целью был реверс-инжиниринг сайта Habitica для разработки requirements artifacts. Rich Picture – это способ изучить ситуацию и выразить ее с помощью диаграмм, показывающих ее течение. Хотя эти изображения не являются официальными документами Habitica, они могут помочь новому разработчику лучше понять как устроен сайт, и помочь в разработке функций и исправлении ошибок. Нажмите на изображения, чтобы увидеть их в высоком разрешении.

Изображения были получены из их проекта вики на https://requisitos-habitica.herokuapp.com/.

RevEngReqmnts-RichPicture-General — Rich Picture показывает общий поток Habitica и то, как Habitica использует свою систему геймификации для решения проблемы скуки при работе над задачами.

RevEngReqmnts-RichPicture-Inventory — Rich Picture показывает как устроена система инвентаря в Habitica.

Работа с локальной копией[]

Для тестирования и разработки кузнецы должны создать локальную копию сайта Habitica. Этот процесс может быть сложен, поэтому мы собрали инструкции по каждой операционной системе на странице «Установка Habitica локально».

Процесс по использованию вашей локальной копии для внесения изменений и создания пул-реквестов описан на этой странице.

MongoDB[]

Чтобы узнать, как использовать MongoDB, мы рекомендуем прочитать официальную документацию MongoDB или другой надежный интернет-ресурс, но вот несколько примеров основных команд, которые помогут новым разработчикам быстро понять, как использовать MongoDB. Вы можете запустить эти команды в интерфейсе командной строки (CLI) MongoDB или с помощью графического интерфейса, например, в Robo 3T IDE от IntelliShell.

В командах ниже знак «$» указывает на использование командной оболочки Unix или Windows или Git, а знак «>» – на использование командной оболочки Mongo CLI. Вводите текст только после этих знаков.

Чтобы получить доступ к оболочке Mongo, а затем выбрать базу данных Habitica вашей локальной копии:

 $ mongo
 > show dbs
 > use habitrpg

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

 $ mongo habitrpg

Просмотр «collections» (коллекций) в базе данных («users», «groups», и др.):

 > show collections

Просмотр всех данных по одному пользователю из коллекции «users» (ID пользователя – 12345678-b5b9-4bb4-8b82-123456789abc):

 > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0]

Просмотр только preferences (настроек) пользователя:

 > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})[0].preferences

Для изменения пользователя используйте метод update вместе с $set:

 > db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {'profile.name': 'New Display Name'}})

На странице «Внесение изменений в сайт Habitica и API с помощью локальной копии» приведены расширенные примеры для конкретных целей, которые могут оказаться полезными для вас при тестировании изменений кода.

Переводимые строки (файлы локалей)[]

Добавление переводимых строк[]

Если вам требуется добавить новую переводимую строку в какой-то шаблон, она должна быть записана в jade-файл следующим образом:

   env.t("stringLabel")

Затем, в директории common/locales/ru, отредактируйте json-файлы, добавив в них новую строку:

       "lastLabel": "Добавить запятую в конец этой строки",
       "stringLabel": "Заголовок строки"
   }

Ни в коем случае не обновляйте json-файлы в других директориях common/locales; переводы контролируются на Transifex.

Чтобы протестировать строку:

остановите npm, если он запущен (нажав Ctrl + C)
выполните npm start

Редактирование переводимых строк[]

Переводимые строки находятся в файлах директории common/locales/ru. Каждая строка состоит из ключа и текста, например:

   "clearAll": "Удалить все сообщения",

Если вам требуется изменить переводимую строку, не изменяйте ключ строки, если нет очень веской причины для этого. Например, если вам нужно изменить «удалить все сообщения» на «стереть все сообщения,» вы не должны изменять ключ «clearAll» на «deleteAll».

Дело в том, что ключ («clearAll») может использовать во многих местах по всему коду Habitica, и изменение ключа приведёт к тому, что от вас может потребовать сделать ненужные изменения в коде.

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

Тесты[]

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

Всякий раз, когда на GitHub приходит пул-реквест, Travis CI запускает все тесты. Любые неудачные тесты рассматриваются, чтобы понять, является ли новый код проблемным.

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

Чтобы запустить тесты из вашей локальной установки, перейдите в корневой каталог и выполните npm test. Это алиас для node_modules/.bin/gulp test, который подготовит тестовую среду и запустит набор тестов.

Чтобы запустить какой-то один тест из вашей локальной установки, выполните mocha test/SUBDIRECTORY/NAME_OF_TEST.coffee.

Изображения[]

Для получения информации о создании новых изображений для Habitica см. Руководство для художников.

Когда новое изображение готово и утверждено сотрудниками, создается ишью, чтобы запросить его добавление в Habitica. Кузнецу нужно будет добавить его в репозиторий. Большинство изображений хранится в соответствующих подкаталогах website/client/assets/

После добавления новых изображения или новых версий существующих, выполните npm run sprites, чтобы перекомплиривать image spritesheets.

Иногда, эта команда приводит к созданию нового spritesheet, в этом случае выполните git add, чтобы добавить новые файлы. Вы найдете их в каталогах website/client/assets/images/sprites/ и website/client/assets/css/sprites/.

Другие полезные команды[]

Поиск кода[]

В консоли, введите:

   grep -R "STRING" *

Чтобы найти строку STRING во всех файлах в текущем каталоге и его под-каталогах.

Если вы хотите выполнить поиск без учёта регистра (например, STRING или String или string), добавьте флаг -i:

   grep -iR "STRING" *

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

Команда grep также принимает регулярное выражение в качестве шаблона для поиска:

   grep -R "REGEX" *

Поиск и замена[]

Вот команда на Perl'е:

   perl -e "s/FROM/TO/g" -pi $(find . -name "*.js")

Замените FROM на строку, которую вы хотите заменить, а TO – на строку, которой вы хотите заменить первую строку. Обратите внимание, что этот пример заменит строки только в JavaScript-файлах (расширение .js), но вы можете указать другие расширения, если хотите.

Если вы хотите заменить все строки, но не их множественное число или другие строки, содержащие эту под-строку (например, заменить weapon из TEST, но не weapons:

   perl -e 's/weapon\b/TEST/g' -pi *

Если вы хотите удалить все строки в JS-файлах, содержащих какое-то ключевое слово:

   perl -ni -e 'print unless /keyword/' -pi $(find . -name "*.js")

Эти команды особенно полезны при работе над переводом.

Предпочитаемые настройки[]

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

Классный совет для хранения настроек[]

В git-обсуждении новой предпочитаемой настройки пользователя прозвучал такой совет: Новые предпочитаемые настройки можно добавлять в website/src/models/user.js, тогда база данных автоматически «заберёт» их (даже если требуется настройка БД).

Раздел «Информация для разработчиков» на других страницах вики[]

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

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

Разделы используют шаблоны {{InfoForDevs Start}} и {{InfoForDevs End}}, чтобы обеспечить правильное форматирование, название кнопок и остальной текст. Чтобы увидеть как это работает, откройте любую страницу, где присутствует этот раздел, в исходном редакторе.

Чтобы увидеть список всех страниц, где есть этот раздел, используйте инструмент «Ссылки сюда» для шаблона «Start».

Если вы хотите, чтобы раздел «Информация для разработчиков» по умолчанию был виден:

Создайте учетную запись на ФЭНДОМЕ, если вы этого ещё не сделали
Отредактируйте ваш личный Wikia.css, который находится по адресу:
https://habitica.fandom.com/ru/wiki/Участник:ВашеИмяПользователя/wikia.css
Вставьте в него эти строки:

    /* Всегда показывать все разделы "Информация для рарзработчиков" */
    .habitrpg-InfoForDevs {
        display:block !important;
    }
    .habitrpg-InfoForDevs-hideIfDev {
        display:none;
    }

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