发布扩展组件

本指南提供将你的开源扩展组件发布至 Jmix 市场 的全部所需内容和配置。

使用我们推荐的方案,需要源代码和二进制制件都在 GitHub 上托管。

或者,也可以将你的扩展组件制件发布至 Maven Central。此时,仅需要为源码创建 GitHub 仓库,组件由你自己发布,然后按照 在市场注册扩展组件 说明进行操作。

创建扩展组件项目

可以用 Jmix Studio 项目创建向导新建 Jmix 扩展组件项目。选择模板 “Single Module 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
        }
    }
}

另外,还要删除 build.gradle 中的版本属性(在 group = 'my.new.jmix.addon' 下面)。然后,在 build.gradle 同级目录创建一个 gradle.properties 文件,包含版本信息:

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 工作流文件添加到仓库中,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@v1

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

      - 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: 1.8
      - 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 支持通过 Web UI 和 CLI 创建发布版。对于 Web UI,首先必须为特定的提交创建一个标签。然后,可以创建相应的发布版。有关更多信息,请参阅 GitHub 文档

如需通过 CLI 创建 GitHub 发布版,请使用此命令:gh release create 0.1.0。将 0.1.0 替换为你想要创建的版本。

我们建议遵循 语义版本控制,根据在此版本中的改动类型来确定新增的版本号。这样用户可以更容易了解版本更新的潜在影响。

发布版创建完成后,GitHub Actions 将创建相应的制件并执行发布。

在市场注册扩展组件

新建 issue

如需将扩展组件发布到 Jmix 组件市场,需要在 jmix-website-content 仓库中创建 issue。选择 “Publish Add-on to Marketplace” 并输入插件名称和它所在的 Github 仓库。

Issue 创建完成后,我们将对扩展组件进行常规检查,如果制件发布在 GitHub Packages 上,则创建代理支持用户从 Jmix 的标准仓库 global.repo.jmix.ionexus.jmix.io 下载。

提交描述

jmix-website-content 仓库的 add-on 目录 创建一个 Pull Request(PR),提交扩展组件的描述文档。我们会合并这个 PR 并在网站发布相应的内容。

如果之后想要更改组件描述,可以在此仓库创建一个新的 PR,包含想要的更改内容。

更新 Jmix BOM

发布版 在 GitHub 上发布后,将能够通过 Jmix 制件仓库 global.repo.jmix.ionexus.jmix.io 下载制件。

通常,Jmix 使用 BOM 集中管理多个兼容版本。可以在 GitHub 上的 jmix-bom 项目中找到为特定 Jmix 版本指定的组件版本。

这种方法的主要好处是用户不必手动查找与他们的 Jmix 版本兼容的扩展组件版本。而是,由组件的发布者在 BOM 中统一声明哪个版本与特定的 Jmix 版本兼容。

如需提交组件版本与 Jmix 版本的兼容性,可以创建相应 release 分支 的 PR。

  1. Fork jmix-framework/jmix 仓库。

  2. 切换至你想要添加版本的 release 分支(例如,release_1_2)。

  3. jmix-bom/bom.gradle 中添加带有 Maven 坐标和正确版本的内容:

    api 'my.new.jmix.addon:my-add-on:1.0.0'
    api 'my.new.jmix.addon:my-add-on-starter:1.0.0'
  4. 创建目标分支的 PR:jmix-framework/jmix 仓库的 release_1_2 分支。

当发布新的主要或次要 Jmix 版本(例如,1.3)时,其 BOM 不包含任何第三方插件,因为没有经过与新版本的兼容性测试。组件开发者应该为相应的 release 分支(例如,release_1_3)提交新的 PR,将扩展组件包含到新的 BOM 中。在组件添加到 BOM 之前,如果用户在其构建脚本中明确指定组件版本,仍然可以在新的 Jmix 版本中使用扩展组件。