发布扩展组件
创建扩展组件项目
可以用 Jmix Studio 项目创建向导新建 Jmix 扩展组件项目。选择模板 “Single Module Add-on”。
在你的扩展组件中,请不要使用 io.jmix.* 作为基础包名和制件的组名。此名称保留给 Jmix 核心扩展组件使用。理想情况下,基础包名应该是你自己的互联网域名的反向 DNS 表示法。
|
由于要与 GitHub Actions 工作流交互(后面介绍),需要修改仓库的设置,将扩展组件的制件发布至 GitHub Packages:
// ...
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
文件,包含版本信息:
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
。
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'
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 会执行下列任务:
-
编译代码
-
运行单元测试和集成测试
-
保存测试结果
-
发布新版本
在市场注册扩展组件
新建 issue
如需将扩展组件发布到 Jmix 组件市场,需要在 jmix-website-content 仓库中创建 issue。选择 “Publish Add-on to Marketplace” 并输入插件名称和它所在的 Github 仓库。
Issue 创建完成后,我们将对扩展组件进行常规检查,如果制件发布在 GitHub Packages 上,则创建代理支持用户从 Jmix 的标准仓库 global.repo.jmix.io
和 nexus.jmix.io
下载。
提交描述
在 jmix-website-content
仓库的 add-on 目录 创建一个 Pull Request(PR),提交扩展组件的描述文档。我们会合并这个 PR 并在网站发布相应的内容。
如果之后想要更改组件描述,可以在此仓库创建一个新的 PR,包含想要的更改内容。
更新 Jmix BOM
发布版 在 GitHub 上发布后,将能够通过 Jmix 制件仓库 global.repo.jmix.io
和 nexus.jmix.io
下载制件。
通常,Jmix 使用 BOM 集中管理多个兼容版本。可以在 GitHub 上的 jmix-bom 项目中找到为特定 Jmix 版本指定的组件版本。
这种方法的主要好处是用户不必手动查找与他们的 Jmix 版本兼容的扩展组件版本。而是,由组件的发布者在 BOM 中统一声明哪个版本与特定的 Jmix 版本兼容。
如需提交组件版本与 Jmix 版本的兼容性,可以创建相应 release 分支 的 PR。
-
Fork jmix-framework/jmix 仓库。
-
切换至你想要添加版本的 release 分支(例如,
release_1_2
)。 -
在
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'
-
创建目标分支的 PR:
jmix-framework/jmix
仓库的release_1_2
分支。
当发布新的主要或次要 Jmix 版本(例如,1.3)时,其 BOM 不包含任何第三方插件,因为没有经过与新版本的兼容性测试。组件开发者应该为相应的 release 分支(例如,release_1_3 )提交新的 PR,将扩展组件包含到新的 BOM 中。在组件添加到 BOM 之前,如果用户在其构建脚本中明确指定组件版本,仍然可以在新的 Jmix 版本中使用扩展组件。
|