Вклад в проект

Хотите помочь?

Помощь приветствуется, особенно в следующих областях:

  • Сообщение об ошибках. Включая те, что унаследованы от DDA.
  • Выявление проблем, не являющихся ошибками. Вводящие в заблуждение описания, значения, явно отличающиеся от аналогичных случаев, грамматические ошибки, странности интерфейса, имеющие очевидное решение.
  • Превращение бесполезных вещей в полезные или их удаление. Добавление рецептов разборки для вещей, у которых они должны быть, но нет; замена полностью избыточных предметов их общими версиями (например, "крошечная помеченная бутылка" на просто "крошечная бутылка") в списках спавна.
  • Работа над тайлсетами. Я периодически добавляю новые объекты, например, новые элементы электросети, и им могут понадобиться новые тайлы.
  • Анализ баланса. Он должен быть достаточно глубоким или "очевидно правильным". "Очевидно правильным" будет что-то вроде: "оружие x имеет строго лучшие характеристики, чем y, но y требует более редких компонентов и имеет в остальном идентичные требования".
  • Выявление узких мест производительности с помощью профилировщика.
  • Помощь с качеством кода.

Как начать

Внести вклад в Cataclysm: Bright Nights просто:

  1. Сделайте форк (Fork) репозитория здесь, на GitHub.
  2. Внесите свои изменения.
  3. Отправьте нам пул-реквест (Pull Request).

Note

Лицензия

Cataclysm: Bright Nights выпускается под лицензией Creative Commons Attribution ShareAlike 3.0. Код и контент игры можно свободно использовать, изменять и распространять для любых целей. Подробности см. на http://creativecommons.org/licenses/by-sa/3.0/. Это означает, что любой ваш вклад в проект также будет подпадать под действие этой лицензии, и эта лицензия является безотзывной.

Руководство

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

  • Добавьте этот репозиторий как upstream (вышестоящий) удаленный репозиторий.
  • Держите вашу ветку main чистой. Это означает, что вы можете легко подтягивать изменения, сделанные в этом репозитории, в свой.
  • Создавайте новую ветку для каждой новой функции или набора связанных исправлений ошибок.
  • Никогда не сливайте (merge) изменения из ваших локальных веток в вашу ветку main. Обновляйте её только путем подтягивания (pull) из upstream/main.

Стиль кода

C++

Стиль кода контролируется во всей кодовой базе с помощью astyle. См. CODE_STYLE для подробностей.

JSON

JSON файлы форматируются с использованием специального форматтера, доступного в tools/format. Посетите Руководство по стилю JSON для подробностей.

Markdown

Markdown файлы, такие как doc/, форматируются с использованием встроенного форматтера deno. Запустите deno fmt где угодно, чтобы отформатировать markdown файлы. В VSCode вы можете установить следующую конфигурацию для автоформатирования markdown файлов при сохранении:

// .vscode/settings.json
{
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "denoland.vscode-deno"
  }
}

Lua

Lua файлы форматируются с использованием встроенного форматтера dprint. Запустите deno task dprint fmt где угодно, чтобы отформатировать Lua файлы. Подробности см. в Руководстве по стилю Lua.

Переводы

Перевод Cataclysm: BN осуществляется с помощью Transifex. Посмотрите проект перевода для получения актуального списка поддерживаемых языков.

Для получения дополнительной информации:

Документация

Комментарии Doxygen

Обширная документация классов и членов классов сделает код более читаемым для новых участников. Новые комментарии doxygen для существующих классов приветствуются.

Используйте следующий шаблон для комментирования классов:

/**
 * Brief description
 *
 * Lengthy description with many words. (optional)
 */
class foo {

}

Используйте следующий шаблон для комментирования функций:

/**
 * Brief description
 *
 * Lengthy description with many words. (optional)
 * @param param1 Description of param1 (optional)
 * @return Description of return (optional)
 */
int foo(int param1);

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

/** Brief description **/
int foo;

Руководство по добавлению документации

  • Комментарии Doxygen должны описывать поведение снаружи, а не реализацию, но так как многие классы в Cataclysm переплетены, часто необходимо описывать реализацию.
  • Описывайте вещи, которые не очевидны новичкам только по названию.
  • Не описывайте избыточно: /** Map **/; map* map; — это бесполезный комментарий.
  • При документировании X описывайте, как X взаимодействует с другими компонентами, а не только то, что делает сам X.

Сборка документации для локального просмотра

  • Установите doxygen
  • doxygen doxygen_doc/doxygen_conf.txt
  • firefox doxygen_doc/html/index.html (замените firefox на ваш браузер)

Пример рабочего процесса

Настройка окружения

(Это нужно сделать только один раз.)

  1. Сделайте форк этого репозитория здесь, на GitHub.

  2. Клонируйте ваш форк локально.

$ git clone https://github.com/YOUR_USERNAME/Cataclysm-BN.git
# Клонирует ваш форк репозитория в текущую директорию в терминале
  1. Установите шаблон сообщения коммита.
$ git config --local commit.template .gitmessage
  1. Добавьте этот репозиторий как удаленный (remote).
$ cd Cataclysm-BN
# Меняет активную директорию на только что клонированную директорию "Cataclysm-BN"
$ git remote add -f upstream https://github.com/cataclysmbn/Cataclysm-BN.git
# Назначает оригинальный репозиторий удаленному репозиторию с именем "upstream"

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

Обновление вашей ветки main

  1. Убедитесь, что ваша ветка main отслеживает main из upstream, а не main из origin, набрав:
$ git branch --set-upstream-to upstream/main main
# заставляет вашу ветку 'main' отслеживать main из upstream.

Чтобы проверить, правильно ли ваша main указывает на upstream, введите git remote -v, и вы должны увидеть что-то вроде:

$ git remote -v

origin  [email protected]:YOUR_USERNAME/Cataclysm-BN.git (fetch)
origin  [email protected]:YOUR_USERNAME/Cataclysm-BN.git (push)
upstream        https://github.com/cataclysmbn/Cataclysm-BN.git (fetch)
upstream        https://github.com/cataclysmbn/Cataclysm-BN.git (push)

и когда вы введете git branch -vv, вы должны увидеть [upstream/main] рядом с веткой main, например:

$ git branch -vv

# ...
* main   ed11439ee61 [upstream/main] feat: add more vending machines to marina (#7001)
# ...
  1. Убедитесь, что вы находитесь в вашей ветке main.
$ git switch main
  1. Подтяните изменения из ветки upstream/main.
$ git pull --ff-only upstream main
# получает изменения из ветки "main" на удаленном репозитории "upstream"

Примечание Если это выдает ошибку, это означает, что вы сделали коммит прямо в вашу локальную ветку main. Нажмите здесь для инструкций, как исправить эту проблему.

Внесение изменений

  1. Обновите вашу ветку main, если вы еще этого не сделали.

  2. Для каждой новой функции или исправления ошибки создавайте новую ветку.

$ git switch --create new_feature
# Создает новую ветку с именем "new_feature" и делает её активной
  1. Как только вы закоммитили некоторые изменения локально, вам нужно запушить (push) их в ваш форк на GitHub.
$ git push origin new_feature
# origin был автоматически настроен указывать на ваш форк при клонировании
  1. Как только вы закончили работу над вашей веткой, закоммитили и запушили все изменения, отправьте пул-реквест из вашей ветки new_feature в ветку main этого репозитория.

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

Примечания к Пул-реквестам

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

Не обязательно решать или ссылаться на открытую задачу (issue) для создания PR, однако, если вы это делаете, вам нужно подробно объяснить проблему, которую решает ваш PR.

Закрытие задач с использованием ключевых слов

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

- {keyword} #{issue}

например: - fixed #12345

ключевое слово

{keyword} должно быть одним из следующих:

  • close, closes, closed
  • fix, fixes, fixed
  • resolve, resolves, resolved

задача

и {issue} — это номер задачи, которую вы закрываете после слияния PR.

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

закрытие нескольких задач сразу

- {keyword} #{issue}, {keyword} #{issue}

См. https://help.github.com/articles/closing-issues-using-keywords для подробностей.

Поддержка инструментов

Доступны различные инструменты, помогающие вам поддерживать ваши вклады в соответствии с надлежащим стилем. См. DEVELOPER_TOOLING для подробностей.

Продвинутые техники

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

Использование веток, отслеживающих удаленные

Ветки, отслеживающие удаленные (remote tracking branches), позволяют вам легко оставаться на связи с веткой main этого репозитория, так как они автоматически знают, из какой удаленной ветки получать изменения.

$ git branch -vv
* main        xxxx [origin/main] ....
  new_feature xxxx ....

Здесь вы видите, что у нас есть две ветки; main, которая отслеживает origin/main, и new_feature, которая не отслеживает ни одной ветки. На практике это означает, что git не будет знать, откуда получать изменения.

$ git checkout new_feature
Switched to branch 'new_feature'
$ git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.

Чтобы легко подтягивать изменения из upstream/main в ветку new_feature, мы можем сказать git, какую ветку она должна отслеживать. (Вы даже можете сделать это для вашей локальной ветки main.)

$ git branch -u upstream/main new_feature
Branch new_feature set up to track remote branch main from upstream.
$ git pull
Updating xxxx..xxxx
....

Вы также можете установить информацию об отслеживании одновременно с созданием ветки.

$ git branch new_feature_2 --track upstream/main
Branch new_feature_2 set up to track remote branch main from upstream.

Примечание: Хотя это упрощает получение изменений из upstream/main, это ничего не меняет в отношении отправки (push). git push не удастся, потому что у вас нет прав на отправку в upstream/main.

$ git push
error: The requested URL returned error: 403 while accessing https://github.com/cataclysmbn/Cataclysm-BN.git
fatal: HTTP request failed
$ git push origin
....
To https://github.com/YOUR_USERNAME/Cataclysm-BN.git
xxxx..xxxx  new_feature -> new_feature

Юнит-тесты

В дереве исходных текстов в tests/ встроен набор тестов. Вы должны запускать набор тестов после ЛЮБОГО изменения в исходном коде игры. Обычный вызов make соберет исполняемый файл теста в tests/cata_test, и его можно вызвать как любой обычный исполняемый файл или через make check. Без аргументов он запустит весь набор тестов. С --help он выведет ряд опций вызова, которые вы можете использовать для настройки его работы.

$ make
... compilation details ...
$ tests/cata_test
Starting the actual test at Fri Nov  9 04:37:03 2018
===============================================================================
All tests passed (1324684 assertions in 94 test cases)
Ended test at Fri Nov  9 04:37:45 2018
The test took 41.772 seconds

Я рекомендую привыкнуть вызывать make как make ВАШИ ОПЦИИ СБОРКИ && make check.

Тестирование в игре, тестовое окружение и меню отладки

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

Откройте меню назначения клавиш (нажмите Escape, затем 1), прокрутите почти до самого низа и нажмите +, чтобы добавить новую привязку клавиш. Нажмите букву, соответствующую пункту Debug menu, затем нажмите клавишу, которую вы хотите использовать для вызова меню отладки. Чтобы протестировать ваши изменения, создайте новый мир с новым персонажем. Как только вы окажетесь в этом мире, нажмите клавишу, которую вы только что назначили для меню отладки, и вы должны увидеть что-то вроде этого:

┌─────────────────────────────────────────────────────┐
│ Debug Functions - Manipulate the fabric of reality! │
├─────────────────────────────────────────────────────┤
│ i Info                                              │
│ Q Quit to main menu                                 │
│ s Spawning...                                       │
│ p Player...                                         │
│ t Teleport...                                       │
│ m Map...                                            │
└─────────────────────────────────────────────────────┘

С помощью этих команд вы сможете воссоздать надлежащие условия для тестирования ваших изменений. Вики BN может содержать полезную информацию о меню отладки.

Часто задаваемые вопросы

Почему git pull --ff-only выдает ошибку?

Если git pull --ff-only показывает ошибку, это означает, что вы сделали коммит прямо в вашу локальную ветку main. Чтобы исправить это, мы создаем новую ветку с этими коммитами, находим точку, в которой мы разошлись с upstream/main, и затем сбрасываем main к этой точке.

$ git pull --ff-only upstream main
From https://github.com/cataclysmbn/Cataclysm-BN
 * branch            main     -> FETCH_HEAD
fatal: Not possible to fast-forward, aborting.
$ git branch new_branch main          # помечаем текущий коммит временной веткой
$ git merge-base main upstream/main
cc31d0... # последний коммит перед тем, как мы закоммитили прямо в main
$ git reset --hard cc31d0....
HEAD is now at cc31d0... ...

Теперь, когда main очищена, мы можем легко подтянуть изменения из upstream/main, а затем продолжить работу в new_branch.

$ git pull --ff-only upstream main
# получает изменения из удаленного репозитория "upstream" для соответствующей ветки, в данном случае "main"
$ git checkout new_branch

Более часто задаваемые вопросы см. в FAQ разработчика.