Вклад в Nau Engine

Добро пожаловать! Мы рады, что вы заинтересовались участием в проекте Nau Engine. Этот документ содержит правила для контрибьюторов проекта, включая описание процесса сообщения об ошибках, предложения новых функций, отправки запросов на слияние (pull requests), а также требования к стилю кода и архитектуре проекта. На данный момет базовый репозитоий размещён на GitHub и для работы можно использовать его функции. Подробные инструкции можно найти по ссылке https://github.com/NauEngine

Важно

Мы призываем всех участников сообщества к уважительному общению и избеганию оскорбительных высказываний.

Сообщите об ошибке

Если вы нашли ошибку, сообщите о ней через систему отслеживания ошибок в GitHub.

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

Важно

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

Пример:

  • Название

    Краткое и точное название проблемы, отражающее суть ошибки. Например: «Ошибка загрузки файла», «Некорректное отображение текстуры».

  • Описание

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

  • Версия

    Версия проекта, которую вы используете. Укажите номер версии и, если известно, релизную ветку (например, «1.2.3 Stable»).

  • Операционная система

    Операционная система, на которой вы столкнулись с ошибкой. Например, «Windows 10».

  • Дополнительная информация

    Скриншоты, логи или другая информация, которая поможет разработчикам понять проблему. Например, «Скриншот ошибки», «Лог ошибок», «Описание конфигурации системы».

Предложите новую функцию

Чтобы предложить новую функцию для проекта, используйте систему отслеживания функций в GitHub. В своем предложении подробно опишите функцию, включая ее назначение, примеры использования, а также потенциальные проблемы или ограничения. Если есть альтернативные способы решения проблемы, опишите их и объясните, почему ваше предложение предпочтительнее.

Пример:

  • Название: краткое и точное название, описывающее функцию.

  • Описание: подробное описание функции, включая ее назначение и преимущества.

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

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

  • Альтернативные решения: если есть альтернативные способы решения проблемы, опишите их и объясните, почему ваше предложение предпочтительнее.

  • Взаимосвязь с проектом Nau Engine. Важно указать:

    • Существующие функции: опишите, как ваша функция будет взаимодействовать с существующими функциями Nau Engine.

    • Влияние на архитектуру: опишите, как реализация функции повлияет на архитектуру Nau Engine.

    • Необходимость в переработке существующего кода: укажите, требует ли реализация функции переработки существующего кода.

    • Сложность реализации: оцените сложность реализации функции.

  • Пример кода: если это возможно, приведите пример кода, иллюстрирующий реализацию функции.

Поделитесь своей идеей с сообществом в канале Nau Engine в Telegram.

Вклад в код (Pull Requests)

Чтобы внести изменения в код проекта, сделайте форк репозитория NauEngine на свою учетную запись GitHub. Создайте новую ветку и внесите свои изменения.

Важно

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

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

  • Написать юнит-тесты. Юнит-тесты — это важная часть процесса разработки, которая позволяет убедиться, что код работает корректно и не содержит ошибок.

    • Покрытие: убедитесь, что ваши тесты покрывают все важные сценарии использования новой функции.

    • Независимость: создайте тесты, которые не зависят друг от друга.

    • Простые и читаемые: напишите тесты таким образом, чтобы их было легко читать и понимать.

  • Оставить комментарии в коде.

  • Зафиксировать изменения с помощью четкого и лаконичного сообщения о фиксации и указать номер тикета.

    • Формат: используйте стандартный формат сообщения о фиксации.

    • Содержание: включите краткое описание изменений.

    • Читаемость: оформите сообщение о фиксации так, чтобы его было легко читать и понимать.

  • Отправить изменения в свой форк.

  • Создать запрос на слияние (pull request) из своей ветки в ветку main основного репозитория.

При создании Pull Request:

  • Придерживайтесь код-стайла NauEngine.

  • Каждый pull request должен решать одну проблему или функцию.

  • Описание запроса на слияние должно четко объяснять изменения и их влияние на проект.

  • Просматривайте отзывы от разработчиков проекта.

  • Используйте GitHub Closing Keywords.

Что нужно знать об архитектуре.

Ознакомьтесь с архитектурой проекта. Изучите основные принципы архитектуры проекта, такие как разделение ответственности, модульность, принцип единой ответственности. Проектируйте свои изменения как модульные и легко тестируемые. Убедитесь, что ваши изменения согласуются с существующей архитектурой проекта.

API проекта

Изучите API проекта, чтобы понять, как различные компоненты проекта работают вместе. Убедитесь, что ваши изменения согласуются с API проекта.

Стиль кода

Изучите правила стиля кода: код-стайл Nau Engine и код-стайл Nau Editor .

  • Отступы: используйте правильное количество пробелов для отступов в коде.

  • Длина строк: не делайте строки кода слишком длинными.

  • Именование переменных и функций: используйте понятные и описательные имена.

  • Комментарии: пишите комментарии к коду в стиле Doxygen.

Используйте последовательный стиль в своем коде. Рассмотрите возможность использования форматировщика кода.

Дополнительные правила

  1. Модули в движке:

    • Создание модуля: создайте новый класс, наследуемый от nau::IModule или nau::DefaultModuleImpl.

    • Подключение модуля:

      • Используйте nau_add_module в CMakeLists.txt модуля.

      • Используйте nau_target_link_public_modules в CMakeLists.txt проекта.

    • Экспорт функционала: используйте макросы NAU_MODULE_EXPORT_SERVICE и NAU_MODULE_EXPORT_CLASS.

    • Жизненный цикл модуля: реализуйте методы initialize(), deinitialize(), postInit(). Для сервисов используйте IServicelnitialization. Для зависимостей используйте IServiceInitialization::getServiceDependencies. Для остановки приложения реализуйте IServiceShutdown. Для экспорта функций используйте declspec(dllexport) и EXPORT_AS_LIBRARY в CMakeLists.txt.

    • Определение экспорта: используйте NAU_[ИМЯ_МОДУЛЯ]_EXPORT, NAU_[ИМЯ_МОДУЛЯ]_BUILD, и макрос IMPLEMENT_MODULE.

  2. USD плагины:

    • Создание USD схемы: используйте стандартный синтаксис USD, определите libraryPrefix, создайте CMakeLists.txt с nau_add_module.

    • Реализация плагина: создайте класс, наследуемый от nau::USD_Plugin, и реализуйте необходимые методы.

    • Использование плагина: используйте API USD.

  1. 3rd party зависимости:

    • Используйте FindPackage в CMakeLists.txt.

    • Проверьте совместимость и лицензию.

    • Включите библиотеку в сборку с помощью target_link_libraries.

    • Документируйте использование.

Лучшие практики

  • Регулярно обновляйте свой форк последними изменениями из основного репозитория через git rebase.

  • Не забывайте тестировать код перед отправкой на слияние.

  • Присоединяйтесь к сообществу Nau Engine в Telegram.

Дополнительная информация

Спасибо за ваш вклад!