Публикация дополнений

Это руководство поможет вам настроить всё необходимое для публикации вашего дополнения с открытым исходным кодом в маркетплейсе Jmix.

С нашим предлагаемым подходом и исходный код, и бинарные артефакты размещаются на GitHub.

Альтернативно, вы можете публиковать артефакты вашего дополнения в Maven Central. В этом случае создайте репозиторий GitHub для вашего исходного кода, настройте публикацию самостоятельно, а затем следуйте инструкциям Регистрация дополнения в Маркетплейсе.

Создание проекта дополнения

Вы можете создать свой новый проект дополнения Jmix через мастер проектов Jmix Studio, используя шаблон Add-On.

Пожалуйста, не используйте io.jmix.* в качестве базового пакета и группы артефактов вашего дополнения. Это имя зарезервировано для основных дополнений Jmix. В идеале базовый пакет должен быть обратной DNS-записью вашего собственного интернет-домена.

Для корректного взаимодействия с рабочими процессами GitHub Actions, которые мы рассмотрим далее, вам следует изменить настройки репозитория для публикации артефактов дополнения в GitHub Packages:

build.gradle

// ...
publishing {
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/" + System.getenv("GITHUB_REPOSITORY"))
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
                password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
            }
        }
    }
    publications {
        javaMaven(MavenPublication) {
            artifactId = archName
            from components.java
        }
    }
}

Дополнительно следует удалить атрибут version в build.gradle (под group = 'my.new.jmix.addon'). Вместо этого создайте файл с именем gradle.properties с информацией о версии непосредственно рядом с файлом build.gradle:

gradle.properties

version=0.0.1-SNAPSHOT

Создание репозитория GitHub

Теперь вам нужен репозиторий GitHub. GitHub предлагает все необходимые компоненты для публикации дополнения с открытым исходным кодом:

хостинг исходного кода
систему непрерывной интеграции (GitHub Actions)
управление пакетами (GitHub Package Registry)

Вы можете создать новый репозиторий GitHub здесь.

Выбор лицензии

Существует несколько лицензий с открытым исходным кодом на выбор. Лицензия Apache, версия 2.0, а также Лицензия MIT, являются распространенными либеральными лицензиями для проектов с открытым исходным кодом. Сам Jmix лицензирован под Apache 2.0.

После выбора лицензии поместите файл лицензии в корневую директорию вашего репозитория GitHub.

Настройка CI

GitHub предлагает встроенную систему CI, которая бесплатно для проектов с открытым исходным кодом компилирует код, запускает тесты, выполняет выпуски релизов и т.д.

Добавив следующие файлы рабочих процессов GitHub Actions в ваш репозиторий GitHub, система CI выполнит компиляцию и запуск автоматизированных тестов. Вам потребуется вручную создать директорию .github/workflows в репозитории.

test.yml

name: CI pipeline

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    name: CI pipeline
    runs-on: ubuntu-latest
    steps:
      - name: Git Checkout
        uses: actions/checkout@v2

      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: '17'

      - name: Make wrapper executable
        run: chmod +x ./gradlew

      - name: Run tests
        run: ./gradlew test

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v2
        if: always() # always run even if the previous step fails
        with:
          report_paths: '**/build/test-results/test/TEST-*.xml'

release.yml

name: Publish release
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v1
        with:
          java-version: '17'
      - name: Publish package
        run: gradle -Pversion=${{ github.event.release.tag_name }} build publish
        env:
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_USERNAME: ${{ github.repository_owner }}
          GITHUB_TOKEN: ${{ github.token }}

При наличии этих двух файлов GitHub Actions будет выполнять следующие задачи:

компиляция кода
запуск модульных / интеграционных тестов
сохранение результатов тестов
публикация новой версии для вновь созданных релизов

Создание релиза

GitHub позволяет создавать релизы через веб-интерфейс и CLI. Для веб-интерфейса сначала необходимо создать тег для определенного коммита. Затем вы можете создать соответствующий релиз. Смотрите документацию GitHub для получения дополнительной информации.

Чтобы создать релиз GitHub через CLI, используйте следующую команду: gh release create 0.1.0. Вы должны заменить 0.1.0 на желаемую версию для создания.

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

После создания релиза GitHub actions создаст артефакт и выпустит его соответствующим образом.

Регистрация дополнения в Маркетплейсе

Создание Issue

Чтобы опубликовать дополнение в Маркетплейсе Jmix, вам необходимо создать issue в репозитории jmix-website-content. Выберите "Publish Add-on to Marketplace" и введите название дополнения и репозиторий GitHub, в котором оно находится.

После того как вы создадите issue, мы проверим дополнение и, если артефакты дополнения опубликованы в GitHub Packages, создадим прокси, чтобы позволить пользователям загружать артефакты из стандартных репозиториев Jmix global.repo.jmix.io и nexus.jmix.io.

Предоставление описания

Создайте PR с описанием вашего дополнения в директории дополнений репозитория jmix-website-content. Мы примем PR и опубликуем контент на сайте.

Если позже вы захотите внести изменения в свое описание, вы можете создать другой PR с желаемыми изменениями в этом репозитории.

Обновление Jmix BOM

После того как релиз будет опубликован на GitHub, вы сможете загружать артефакт через репозитории артефактов Jmix global.repo.jmix.io и nexus.jmix.io.

Как правило, Jmix работает с BOM (Bill of Materials) для централизованного управления совместимыми версиями. Версии, указанные для данного релиза Jmix, можно найти в проекте jmix-bom на GitHub.

Основное преимущество этого подхода заключается в том, что пользователям не нужно вручную выяснять правильную версию вашего дополнения, совместимую с их версией Jmix. Вместо этого вы объявляете, какая версия корректно работает с конкретным релизом Jmix, централизованно в BOM.

Чтобы связать ваш релиз с конкретной версией Jmix, создайте issue на https://github.com/jmix-framework/jmix/issues и укажите совместимые версии дополнения и Jmix.

Альтернативно, вы можете создать PR в соответствующую ветку релиза.

Сделайте форк репозитория jmix-framework/jmix.
Переключитесь на ветку релиза Jmix, в которую вы хотите добавить свой релиз (например, release_2_7_ru).
Добавьте строку с вашими Maven-координатами и правильной версией в jmix-bom/bom.gradle после комментария community add-ons:
bom.gradle
```
// community add-ons
// ...
api 'my.new.jmix.addon:my-add-on:1.0.0'
api 'my.new.jmix.addon:my-add-on-starter:1.0.0'
// end community add-ons
```
Создайте PR с целевой веткой: release_2_7_ru репозитория jmix-framework/jmix.

Когда выпускается новая мажорная или минорная версия Jmix (например, 5.5.0), её BOM не содержит сторонних дополнений, поскольку они не протестированы на совместимость с новой версией.

Вам следует создать новый issue или отправить PR для соответствующей ветки релиза (например, release_5_5), чтобы включить ваше дополнение в новый BOM. Пока ваше дополнение не находится в BOM, пользователи всё равно могут использовать ваше дополнение с новой версией Jmix, если они явно укажут версию дополнения в своих скриптах сборки.