Внесение вклада в CUBA Platform

Эти инструкции предназначены для внесения кода в основной фреймворк.

Сообщение об ошибках

Если вы хотите обсудить вашу проблему или задать вопрос, пожалуйста, используйте наш форум: https://www.cuba-platform.com/discuss. Пройдите по существующим проблемам перед добавлением новой — вероятность того, что кто-то уже столкнулся с такой же проблемой, очень высока. Оставьте комментарий к существующей проблеме, чтобы сообщить нам о её релевантности для вас или добавить больше деталей.

Отправка патчей

Все наши проекты принимают вклад в виде GitHub pull requests. В первый раз, когда вы создаёте pull request, вас попросят электронно подписать соглашение о вкладе.

https://yangsu.github.io/pull-request-tutorial/ содержит инструкции по созданию pull request.

Помните, чтобы проверить "Allow edits from maintainers", чтобы мы могли перебазировать PR или сделать небольшие изменения, если это необходимо.

Обычно мы создаём проблему для PR в нашем внутреннем трекере ошибок (YouTrack) и добавляем номер проблемы в заголовок PR.

5 Шагов для внесения патча в CUBA Platform

1. Создайте pull request
2. Подпишите CLA
3. Ответьте на комментарии к вашему вкладу
4. Исправьте проблемы кода и стиля
5. Подождите слияния и выпуска

Настройка проекта

CUBA Platform состоит из двух основных проектов:

• cuba-gradle-plugin https://github.com/cuba-platform/cuba-gradle-plugin
• cuba https://github.com/cuba-platform/cuba### Сборка из исходного кода Предположим, что вы склонировали CUBA Gradle Plugin и CUBA в следующие директории:

work/
    cuba/
    cuba-gradle-plugin/

Все детали сборки CUBA и Gradle задачи реализованы в cuba-gradle-plugin.

Откройте терминал в директории work и выполните следующую команду для сборки и установки плагина в ваш локальный Maven репозиторий (~/.m2):

> cd cuba-gradle-plugin
> gradlew install

Это соберёт и установит -SNAPSHOT версию cuba-gradle-plugin, необходимую для сборки платформы.

После этого перейдите в директорию CUBA и соберите и установите её с помощью той же команды:

> cd ../cuba
> gradlew install

Если возникли ошибки во время компиляции, пожалуйста, проверьте статус нашей публичной сборки по адресу https://travis-ci.org/cuba-platform. Не стесняйтесь сообщать нам о любых проблемах с сборкой!

Импорт в IDE

Мы используем IntelliJ IDEA IDE для разработки. Чтобы работать с CUBA, его нужно импортировать как проект в IntelliJ IDEA. Для этого выполните следующие шаги:

• File > Open > CUBA корневая директория > build.gradle
• Открыть как проект
• Принять настройки в диалоговом окне импорта проекта

Дополнительные детали о том, как импортировать проект в IntelliJ IDEA.

Запуск CUBA как приложенияCUBA сам по себе может запускаться как приложение с встроенной базой данных HSQL. Это очень удобно, если вы хотите проверить изменения в стандартной функциональности пользовательского интерфейса, не создавая дополнительных образцов проектов.Сначала запустите встроенную базу данных:

> gradlew startDb createDb

Извлеките локальный экземпляр Tomcat (Tomcat будет извлечен в рабочую директорию на том же уровне, что и директории cuba и cuba-gradle-plugin):

> gradlew setupTomcat

Разверните и запустите CUBA:

> gradlew deploy start

Веб-интерфейс CUBA будет доступен по адресу http://localhost:8080/cuba/

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

> gradlew restart

Запуск тестов

CUBA включает стандартные юнит-тесты и интеграционные тесты, которые требуют встроенной базы данных и контекста Spring. См. этот раздел документации: https://doc.cuba-platform.com/manual-latest/testing.html

Чтобы запустить все тесты, используйте следующую команду:

> gradlew startDb createTestDb test

Также вы можете легко запустить конкретный тест из IntelliJ IDEA, но помните, что перед запуском интеграционных тестов необходимо запустить HSQL DB и создать тестовую базу данных.

Статический анализ кода

Чтобы запустить статический анализ кода, используйте следующую команду:

> gradlew javadoc findbugsMain

Проверка обновлений зависимостей Maven

1. Установите соответствующий плагин cuba-gradle-plugin в .m2
2. Выполните команду:

> gradlew dependencyUpdates -PdependencyUpdates -Drevision=release

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

Руководство по процессу разработки### Стиль кода

1. Файлы исходного кода (Java, XML и Groovy) должны содержать уведомление об авторском праве с лицензией Apache 2.0. Это будет сгенерировано автоматически, если вы используете среду разработки IntelliJ IDEA.
2. Используйте стандартные параметры форматирования кода в IntelliJ IDEA. Вы можете реформатировать свой код (только измененный код!) с помощью сочетания клавиш Ctrl+Alt+L.
3. Максимальная длина строки — 120 символов.
4. Рекомендуемая длина метода — до 50 строк.
5. Все публичные интерфейсы, классы и их публичные методы должны содержать аннотацию JavaDoc (исключая сущности и простые геттеры/сеттеры).
6. Все переопределенные методы должны содержать аннотацию @Override.
7. Зарезервированные слова SQL — нижний регистр.
8. Идентификаторы SQL (названия таблиц, названия столбцов и т.д.) — UPPERCASE_WITH_UNDERSCORES.
9. Если вы изменяете модель данных — вам необходимо предоставить SQL-скрипты создания/обновления для всех поддерживаемых баз данных: HSQL, PostgreSQL, MySQL, MS SQL, Oracle.
10. Скрипты обновления SQL должны быть названы в формате -yourScriptName.sql: 170719-addedAuditTable.sql

Пулл-запросы1. Все ветки с новыми функциями должны называться как "feature/some-feature-name". Не называйте свою ветку номером задачи YouTrack, имя ветки должно описывать её назначение.

1. Если вы решаете существующую проблему, описанную в одной из задач нашего внутреннего трекера багов, добавьте номер задачи в начало вашего сообщения о коммите. Если проблема не описана в нашем трекере багов, мы создадим задачу и добавим номер задачи в сообщение о коммите при слиянии пулл-запроса.
2. Решайте только одну проблему на патч.
3. Опишите ваши изменения и их влияние на пользователя: что вы изменили, почему вы это изменили, как вы это изменили?
4. Включите тест, чтобы доказать, что ваш патч работает. Предпочтительны юнит-тесты.
5. Проверьте стиль ваших изменений: можно иметь отдельный коммит для исправления стилистических проблем.
6. Соберите проект и запустите тесты перед отправкой патча.
7. Создайте пулл-запрос; он будет проверен командой платформы. Не забудьте поставить галочку "Разрешить редактирование от поддержки", чтобы мы могли пересобирать PR или делать небольшие изменения, если это необходимо.
8. После отправки вашего изменения будьте терпеливы и подождите. Проверяющие заняты и могут не сразу проверить ваш патч. Идеально, если мы получаем ответ в течение одного рабочего дня. 1.Отвечайте на комментарии проверяющих: комментарии проверяющих предназначены для улучшения качества кода, указывая на дефекты или проблемы читаемости.
9. Большинство пулл-запросов проходят несколько итераций проверки перед тем, как быть принятыми.Мы с нетерпением ждем ваших вкладов!