diff --git a/docs/developer-guide/app-store/publish-app.md b/docs/developer-guide/app-store/publish-app.md index c48394bb..9ff32968 100644 --- a/docs/developer-guide/app-store/publish-app.md +++ b/docs/developer-guide/app-store/publish-app.md @@ -1,57 +1,257 @@ --- title: 发布应用 -description: 了解如何在 Halo 应用市场创建应用并提交审核 +description: 了解如何准备、提交并维护 Halo 应用市场中的主题和插件 --- +本页按发布前准备、首次上架、审核处理和发布后维护的顺序，说明如何将主题或插件发布到 Halo 应用市场。下文以应用统称主题和插件。 + Halo 官方应用市场支持开发者自助创建应用并提交首次上架审核。当前自助上架流程主要面向免费插件和主题；付费上架、平台代收、结算、分账等能力暂未开放。 +## 发布流程概览 + +首次上架建议按以下顺序完成： + +1. 准备应用仓库、版本号、构建产物、README、许可证、截图和支持入口。 +2. 申请成为 Halo 应用市场开发者。 +3. 创建应用，填写应用类型、名称、简介、Logo、截图、README、外部链接等上架信息。 +4. 创建首个版本，填写版本号、Halo 兼容范围和版本说明，并上传版本制品。 +5. 对照[应用市场审核指南](./app-review-guidelines.md)完成自查，然后提交首次审核。 +6. 根据审核结果发布、整改或重新提交。 + +应用通过首次审核后，后续版本可以继续在应用管理页面维护，也可以接入 GitHub Actions 自动发布。 + +## 发布前准备 + +### 托管代码和收集反馈 + +如果你的应用是开源应用，推荐将代码托管在 GitHub 上。这样可以： + +1. 使用 GitHub Actions 等 CI/CD 工具自动构建和发布版本。 +2. 使用 GitHub Issues 跟踪用户反馈和缺陷报告。 +3. 让更多用户和贡献者发现你的应用。 + +除此之外，可以为 GitHub 仓库添加与 Halo 相关的 [Topics](https://github.com/topics)，以便让更多用户找到你的应用。主题可以添加 [#halo-theme](https://github.com/topics/halo-theme)，插件可以添加 [#halo-plugin](https://github.com/topics/halo-plugin)。 + +### 准备上架资料 + +创建应用前，建议先准备以下资料： + +1. 应用名称、简介、Logo、截图和 README。 +2. 许可证、开源仓库、问题反馈地址、支持地址或主页地址。 +3. 安装、配置、使用、升级、卸载和故障排查说明。 +4. 涉及第三方服务、用户数据、商业限制、外部授权或付费能力时，对应的说明文档。 +5. 至少一个可安装的版本制品。插件通常应提供 JAR 包，主题通常应提供 ZIP 包。 + +这些资料会直接影响审核和用户理解成本。提交前请确认内容真实准确，并与应用实际功能保持一致。 + +### 使用语义化版本号 {#version-control} + +版本号应遵循 [Semantic Versioning](https://semver.org/) 规范，使用 `MAJOR.MINOR.PATCH` 的形式： + +1. 不兼容变更增加 `MAJOR`。 +2. 向后兼容的新功能增加 `MINOR`。 +3. 向后兼容的问题修复增加 `PATCH`。 + +已经发布的版本不应再修改对应制品。如需修复问题，请发布新版本。预发布版本可以使用 `1.0.0-alpha.1`、`1.0.0-beta.1`、`1.0.0-rc.1` 这样的格式。 + +Halo 兼容范围也应填写合法的 Semantic Versioning range，例如 `>=2.20.0`。不要在版本号或兼容范围前后保留空白字符。 + +### 创建 GitHub Release + +当应用完成开发并经过充分测试后，可以在 GitHub 上创建新的 Release。GitHub Release 基于 Git tag，用于发布可供用户下载的软件版本，也可以附加编译后的二进制文件。 + +如果你暂时不接入自动发布，可以在 GitHub Release 中手动上传构建好的 JAR 或 ZIP 文件；如果使用下文的 CI/CD 工作流，Release 发布时会自动构建并上传制品。 + ## 申请成为开发者 -上架应用前，你需要使用已完成邮箱验证的 Halo 官网账号，在[开发者入驻页面](https://www.halo.run/uc/developer/join)申请成为应用市场开发者。申请时需要填写开发者资料，并阅读和同意当前开发者协议。申请通过后，你可以在[应用管理页面](https://www.halo.run/uc/developer/apps)创建和管理自己的应用。 +上架应用前，你需要使用已完成邮箱验证的 Halo 官网账号，在[开发者入驻页面](https://www.halo.run/uc/developer/join)申请成为应用市场开发者。申请时需要填写开发者资料，并阅读和同意当前开发者协议。 + +申请通过后，可以在[应用管理页面](https://www.halo.run/uc/developer/apps)创建和管理自己的应用。如果申请被驳回，可以根据审核意见修改资料后重新提交。待审核的开发者申请可以取消，取消后也可以重新提交。 -如果申请被驳回，可以根据审核意见修改资料后重新提交。待审核的开发者申请可以取消，取消后也可以重新提交。 +## 创建应用和首个版本 -## 首次上架流程 +### 创建应用 -首次上架应用需要经过应用级审核。建议按以下顺序准备： +在[应用管理页面](https://www.halo.run/uc/developer/apps)创建应用时，需要填写应用类型、名称、简介、Logo、截图、README、许可证、外部链接、开源仓库或支持地址等信息。 -1. 在[应用管理页面](https://www.halo.run/uc/developer/apps)创建应用，填写应用类型、名称、简介、Logo、截图、README、许可证、外部链接、开源仓库或支持地址等上架信息。 -2. 创建首个版本，填写版本号、Halo 兼容范围和版本说明。版本号应符合 Semantic Versioning 规范，Halo 兼容范围应是合法的 Semantic Versioning range。 -3. 上传版本制品。插件通常应上传可安装的 JAR 包，主题通常应上传可安装的 ZIP 包。 -4. 对照[应用市场审核指南](./app-review-guidelines.md)完成提交前自查。 -5. 提交审核，阅读并同意应用上架协议；如应用需要测试账号、演示环境、特殊安装步骤或重新提交说明，可以在提交说明中补充。 +上架信息应准确反映应用的实际功能、限制和使用成本。涉及隐私、第三方服务、外部授权或商业限制时，应在 README 或相关字段中明确说明。 + +### 创建首个版本 + +创建应用后，需要继续创建首个版本： + +1. 填写版本号。 +2. 填写 Halo 兼容范围。 +3. 填写版本说明。 +4. 上传版本制品。 首次提交审核前，应用应仍处于草稿状态，并且仅保留一个初始草稿版本。该版本至少需要包含一个上传完成的制品。 -## 审核期间 +## 提交首次审核 + +首次上架应用需要经过应用级审核。提交前请先对照[应用市场审核指南](./app-review-guidelines.md)完成自查，重点确认： + +1. 应用可以在声明兼容的 Halo 版本中完成安装、启用、配置、使用、禁用和卸载。 +2. 上架信息、截图、README、版本说明和外部链接真实准确。 +3. 版本号和 Halo 兼容范围格式正确。 +4. 插件 `plugin.yaml` 中的 logo 字段已正确设置，不能继续使用插件开发模板中的默认 Halo 图标。 +5. 主题和插件的描述文件中已正确设置 `homepage`、`issues`、`license` 字段。 +6. 许可证、第三方资源、商标、图片、字体、图标和模板授权清晰。 +7. 应用不包含恶意代码、未披露数据收集、隐藏远程执行、高危安全漏洞或违法违规内容。 + +提交审核时需要阅读并同意应用上架协议。如应用需要测试账号、演示环境、特殊安装步骤或重新提交说明，可以在提交说明中补充。 + +## 审核期间和审核结果 -提交审核后，平台会保存提交当时的应用信息、README、初始版本、版本说明、制品和协议确认信息作为审核快照。审核期间如需修改应用、版本、说明或制品，应取消审核、等待驳回后重新提交，或按审核意见处理。 +提交审核后，平台会保存提交当时的应用信息、README、初始版本、版本说明、制品和协议确认信息作为审核快照。 -审核通过后，应用会发布到应用市场。审核被拒时，审核意见可能引用[应用市场审核指南](./app-review-guidelines.md)中的条款编号，你需要按对应条款整改后重新提交。即使应用已经通过审核，后续版本、重大更新或出现风险、投诉时，仍可能被重新审核、暂停分发或下架。 +审核期间如需修改应用、版本、说明或制品，应取消审核、等待驳回后重新提交，或按审核意见处理。 -## 上架要求 +审核通过后，应用会发布到应用市场。审核被拒时，审核意见可能引用[应用市场审核指南](./app-review-guidelines.md)中的条款编号，你需要按对应条款整改后重新提交。 -在你决定上架到 Halo 应用市场前，请确保已经完成以下要求： +即使应用已经通过审核，后续版本、重大更新或出现风险、投诉时，仍可能被重新审核、暂停分发或下架。 -1. 插件必须正确设置 `plugin.yaml` 中的 logo 字段，不能是插件开发模板中默认的 Halo 图标。 -2. 主题和插件的描述文件中必须正确设置 `homepage`、`issues`、`license` 字段，详细解释： - 1. `homepage`：应用的主页，可以填写为 GitHub 仓库地址或者 Halo 应用市场的应用详情页地址。 - 2. `issues`：应用的反馈地址，可以填写为 GitHub 仓库的 issues 地址。 - 3. `license`：应用的发行许可证。 -3. 应用必须编写介绍和使用文档。 -4. 应用如果是基于其他程序开发的，需要保证许可证兼容。 -5. 应用的截图、说明、外部链接、隐私说明、第三方服务说明和商业限制应真实准确，并与应用实际功能保持一致。 -6. 应用不得包含恶意代码、未披露数据收集、隐藏远程执行、高危安全漏洞或违法违规内容。 +## 发布后维护 -更多审核规则请查阅[应用市场审核指南](./app-review-guidelines.md)。 +### 手动发布后续版本 -## 后续版本和自动发布 +应用首次审核通过后，开发者可以在[应用管理页面](https://www.halo.run/uc/developer/apps)为自己拥有的应用发布后续版本。 -应用首次审核通过后，开发者可以在[应用管理页面](https://www.halo.run/uc/developer/apps)为自己拥有的应用发布后续版本。后续版本仍应符合[应用市场审核指南](./app-review-guidelines.md)，但当前流程不会为每个后续版本创建独立审核记录。 +后续版本仍应符合[应用市场审核指南](./app-review-guidelines.md)。当前流程不会为每个后续版本创建独立审核记录，但开发者仍应确保版本制品、版本说明、兼容范围和上架资料准确可靠。 -如果你希望在 GitHub 发布 Release 后自动同步后续版本到应用市场，可以修改 CI / CD 工作流： +### 分享应用 + +为了让更多 Halo 用户知道你的应用，可以在以下渠道分享： + +1. [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo)：你可以向这个仓库发起 PR 提交应用信息。 +2. [Halo 论坛](https://bbs.halo.run/t/plugins)：你可以在 Halo 官方社区的[插件](https://bbs.halo.run/t/plugins)和[主题](https://bbs.halo.run/t/themes)板块发布应用。 + +### 使用 GitHub Actions 自动构建和发布 + +Halo 的主题和插件可以使用 [halo-sigs/reusable-workflows](https://github.com/halo-sigs/reusable-workflows) 提供的 GitHub Actions 工作流自动构建，并在 GitHub Release 发布时上传制品。 + +首次审核前，建议先让 CD 工作流只上传 GitHub Release 资产，不自动同步到应用市场。应用首次审核通过后，再补充应用 ID 和个人令牌，用于自动同步后续版本。 + +插件 CI 示例： + +```yaml title=".github/workflows/ci.yaml" +name: CI + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + ci: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-ci.yaml@v4 + with: + ui-path: "ui" +``` + +插件 CD 示例，仅上传 GitHub Release 资产： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v4 + permissions: + contents: write + with: + ui-path: "ui" + skip-appstore-release: true +``` + +主题 CD 示例，仅上传 GitHub Release 资产： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v4 + permissions: + contents: write + with: + skip-appstore-release: true +``` + +使用 `theme-cd.yaml` 发布主题时，主题仓库需要使用 pnpm，并在 `package.json` 中提供 `build` 脚本。该脚本需要执行 `npx @halo-dev/theme-package-cli`；如果主题还有其他构建步骤，应先执行这些步骤，再执行主题打包命令。 + +```json title="package.json" +{ + "scripts": { + "build": "vite build && npx @halo-dev/theme-package-cli" + } +} +``` + +### 自动同步后续版本到应用市场 + +应用首次审核通过后，如果希望在 GitHub 发布 Release 时自动同步后续版本到应用市场，可以调整 CD 工作流： 1. 移除 `skip-appstore-release: true` 配置，或者设置为 `false`。 2. 在 `with` 中添加 `app-id` 配置，值为应用市场的应用 ID，可在[应用管理页面](https://www.halo.run/uc/developer/apps)查看。 -3. 在 Halo 官网的个人中心创建一个新的[个人令牌](https://www.halo.run/uc/profile?tab=pat)，勾选 **应用市场开发者 > 版本管理**。 +3. 在 Halo 官网的个人中心创建新的[个人令牌](https://www.halo.run/uc/profile?tab=pat)，勾选 **应用市场开发者 > 版本管理**。 4. 在 GitHub 仓库的设置 -> `Secrets and variables` 中新建一个 Secret，名称为 `HALO_PAT`，值为你在 Halo 官网创建的个人令牌。 +5. 在工作流中将 `HALO_PAT` 映射为 reusable workflow 需要的 `halo-pat`。 + +插件 CD 示例，自动同步到应用市场： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v4 + secrets: + halo-pat: ${{ secrets.HALO_PAT }} + permissions: + contents: write + with: + app-id: app-xxxxxxxx + ui-path: "ui" +``` + +主题 CD 示例，自动同步到应用市场： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v4 + secrets: + halo-pat: ${{ secrets.HALO_PAT }} + permissions: + contents: write + with: + app-id: app-xxxxxxxx +``` + +以上插件示例假设 UI 子项目路径为 `ui`；如果你的仓库使用默认的 `console` 路径，可以移除 `ui-path`，或按实际结构调整。若项目使用 Corepack 并且已在 `package.json` 中定义 `packageManager`，可以参考 `halo-sigs/reusable-workflows` 的说明调整 `pnpm-version`。 diff --git a/docs/developer-guide/appendix/publish-app.md b/docs/developer-guide/appendix/publish-app.md deleted file mode 100644 index bf5a85c9..00000000 --- a/docs/developer-guide/appendix/publish-app.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: 发布应用 -description: 了解如何与我们的社区分享你的主题和插件 ---- - -了解如何与我们的社区分享你的主题和插件，下文以应用统称主题和插件。 - -## GitHub 托管 - -如果你的应用是一个开源应用，那么我们推荐将其托管在 GitHub 上，可以获得以下好处： - -1. 可以利用 GitHub 的 CI/CD 功能，实现自动构建和版本发布。 -2. 可以通过 GitHub 的 Issues 功能跟踪用户反馈。 -3. 可以获得更多用户关注和贡献。 - -除此之外，我们推荐为 GitHub 仓库添加与 Halo 相关的 [Topics](https://github.com/topics)，以便让更多用户找到你的应用，比如主题可以添加 [#halo-theme](https://github.com/topics/halo-theme)，插件可以添加 [#halo-plugin](https://github.com/topics/halo-plugin)。 - -## 版本发布 - -当你完成了你的应用并进行充分测试后，就可以在 GitHub 上创建新的 Release，其中版本规范可以参考[版本控制](#version-control)。 - -### 集成 CI / CD - -我们为 Halo 的主题和插件提供了适用于 GitHub Action 的 CI / CD [工作流](https://github.com/halo-sigs/reusable-workflows)，可以非常方便的集成到你的 GitHub 仓库中，以下是示例： - -插件 CI： - -```yaml title=".github/workflows/ci.yaml" -name: CI - -on: - push: - branches: - - main - pull_request: - branches: - - main - -jobs: - ci: - uses: halo-sigs/reusable-workflows/.github/workflows/plugin-ci.yaml@v3 - with: - ui-path: "ui" - pnpm-version: 9 - node-version: 22 - java-version: 21 -``` - -插件 CD： - -此工作流会在每次发布 Release 时自动执行，会自动构建插件并上传产物到 Release 的 Assets 中。 - -```yaml title=".github/workflows/cd.yaml" -name: CD - -on: - release: - types: - - published - -jobs: - cd: - uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v3 - permissions: - contents: write - with: - pnpm-version: 9 - node-version: 22 - java-version: 21 - skip-appstore-release: true -``` - -主题 CD： - -此工作流会在每次发布 Release 时自动执行，会自动构建主题并上传产物到 Release 的 Assets 中。 - -```yaml title=".github/workflows/cd.yaml" -name: CD - -on: - release: - types: - - published - -jobs: - cd: - uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v3 - permissions: - contents: write - with: - skip-appstore-release: true - node-version: 22 - pnpm-version: 9 -``` - -关于 CI / CD 的更多详细信息，可查阅：[halo-sigs/reusable-workflows](https://github.com/halo-sigs/reusable-workflows) - -## 分享应用 - -为了方便让 Halo 的用户知道你的应用，可以在以下渠道分享： - -1. [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo)：你可以向这个仓库发起一个 PR 提交你的应用信息。 -2. [Halo 论坛](https://bbs.halo.run/t/plugins)：你可以在 Halo 官方社区的[插件](https://bbs.halo.run/t/plugins)和[主题](https://bbs.halo.run/t/themes)板块发布你的应用。 - -## 发布到应用市场 - -Halo 官方应用市场支持开发者自助创建应用并提交首次上架审核。具体流程请查阅[应用市场 / 发布应用](../app-store/publish-app.md)，提交前请对照[应用市场审核指南](../app-store/app-review-guidelines.md)完成自查。 - -## 版本控制 {#version-control} - -为了保持 Halo 生态系统的健康、可靠和安全，每次你对自己拥有的应用进行重大更新时，我们建议在遵循 [semantic versioning spec](http://semver.org/) 的基础上发布新版本。遵循语义版本控制规范有助于其他依赖你代码的开发人员了解给定版本的更改程度，并在必要时调整自己的代码。 diff --git a/docs/developer-guide/plugin/interaction/dependency.md b/docs/developer-guide/plugin/interaction/dependency.md index 6aebd335..b16b9e6d 100644 --- a/docs/developer-guide/plugin/interaction/dependency.md +++ b/docs/developer-guide/plugin/interaction/dependency.md @@ -328,4 +328,4 @@ jobs: API 模块和插件模块的版本应该保持一致，以确保插件在不同环境中的一致性。 -版本的发布应该遵循 [语义化版本规范](../../appendix/publish-app.md#version-control)，以确保插件的版本号能够清晰地表达插件的变化和向后兼容性。 +版本的发布应该遵循 [语义化版本规范](../../app-store/publish-app.md#version-control)，以确保插件的版本号能够清晰地表达插件的变化和向后兼容性。 diff --git a/docusaurus.config.js b/docusaurus.config.js index ee92a5c1..a4a6d5de 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -87,7 +87,7 @@ const config = { "/2.21/**", "/2.22/**", "/2.23/**", - "/2.24/**" + "/2.24/**", ], }, googleAnalytics: { @@ -242,6 +242,17 @@ const config = { plugins: [ require.resolve("docusaurus-plugin-image-zoom"), require.resolve("docusaurus-plugin-sass"), + [ + require.resolve("@docusaurus/plugin-client-redirects"), + { + redirects: [ + { + from: "/developer-guide/appendix/publish-app", + to: "/developer-guide/app-store/publish-app", + }, + ], + }, + ], ], scripts: [ { diff --git a/sidebars.js b/sidebars.js index c02ce5ef..8903db91 100644 --- a/sidebars.js +++ b/sidebars.js @@ -467,13 +467,5 @@ module.exports = { }, "developer-guide/form-schema", "developer-guide/annotations-form", - { - type: "category", - label: "附录", - link: { - type: "generated-index", - }, - items: ["developer-guide/appendix/publish-app"], - }, ], }; diff --git a/versioned_docs/version-2.25/developer-guide/app-store/publish-app.md b/versioned_docs/version-2.25/developer-guide/app-store/publish-app.md index c48394bb..9ff32968 100644 --- a/versioned_docs/version-2.25/developer-guide/app-store/publish-app.md +++ b/versioned_docs/version-2.25/developer-guide/app-store/publish-app.md @@ -1,57 +1,257 @@ --- title: 发布应用 -description: 了解如何在 Halo 应用市场创建应用并提交审核 +description: 了解如何准备、提交并维护 Halo 应用市场中的主题和插件 --- +本页按发布前准备、首次上架、审核处理和发布后维护的顺序，说明如何将主题或插件发布到 Halo 应用市场。下文以应用统称主题和插件。 + Halo 官方应用市场支持开发者自助创建应用并提交首次上架审核。当前自助上架流程主要面向免费插件和主题；付费上架、平台代收、结算、分账等能力暂未开放。 +## 发布流程概览 + +首次上架建议按以下顺序完成： + +1. 准备应用仓库、版本号、构建产物、README、许可证、截图和支持入口。 +2. 申请成为 Halo 应用市场开发者。 +3. 创建应用，填写应用类型、名称、简介、Logo、截图、README、外部链接等上架信息。 +4. 创建首个版本，填写版本号、Halo 兼容范围和版本说明，并上传版本制品。 +5. 对照[应用市场审核指南](./app-review-guidelines.md)完成自查，然后提交首次审核。 +6. 根据审核结果发布、整改或重新提交。 + +应用通过首次审核后，后续版本可以继续在应用管理页面维护，也可以接入 GitHub Actions 自动发布。 + +## 发布前准备 + +### 托管代码和收集反馈 + +如果你的应用是开源应用，推荐将代码托管在 GitHub 上。这样可以： + +1. 使用 GitHub Actions 等 CI/CD 工具自动构建和发布版本。 +2. 使用 GitHub Issues 跟踪用户反馈和缺陷报告。 +3. 让更多用户和贡献者发现你的应用。 + +除此之外，可以为 GitHub 仓库添加与 Halo 相关的 [Topics](https://github.com/topics)，以便让更多用户找到你的应用。主题可以添加 [#halo-theme](https://github.com/topics/halo-theme)，插件可以添加 [#halo-plugin](https://github.com/topics/halo-plugin)。 + +### 准备上架资料 + +创建应用前，建议先准备以下资料： + +1. 应用名称、简介、Logo、截图和 README。 +2. 许可证、开源仓库、问题反馈地址、支持地址或主页地址。 +3. 安装、配置、使用、升级、卸载和故障排查说明。 +4. 涉及第三方服务、用户数据、商业限制、外部授权或付费能力时，对应的说明文档。 +5. 至少一个可安装的版本制品。插件通常应提供 JAR 包，主题通常应提供 ZIP 包。 + +这些资料会直接影响审核和用户理解成本。提交前请确认内容真实准确，并与应用实际功能保持一致。 + +### 使用语义化版本号 {#version-control} + +版本号应遵循 [Semantic Versioning](https://semver.org/) 规范，使用 `MAJOR.MINOR.PATCH` 的形式： + +1. 不兼容变更增加 `MAJOR`。 +2. 向后兼容的新功能增加 `MINOR`。 +3. 向后兼容的问题修复增加 `PATCH`。 + +已经发布的版本不应再修改对应制品。如需修复问题，请发布新版本。预发布版本可以使用 `1.0.0-alpha.1`、`1.0.0-beta.1`、`1.0.0-rc.1` 这样的格式。 + +Halo 兼容范围也应填写合法的 Semantic Versioning range，例如 `>=2.20.0`。不要在版本号或兼容范围前后保留空白字符。 + +### 创建 GitHub Release + +当应用完成开发并经过充分测试后，可以在 GitHub 上创建新的 Release。GitHub Release 基于 Git tag，用于发布可供用户下载的软件版本，也可以附加编译后的二进制文件。 + +如果你暂时不接入自动发布，可以在 GitHub Release 中手动上传构建好的 JAR 或 ZIP 文件；如果使用下文的 CI/CD 工作流，Release 发布时会自动构建并上传制品。 + ## 申请成为开发者 -上架应用前，你需要使用已完成邮箱验证的 Halo 官网账号，在[开发者入驻页面](https://www.halo.run/uc/developer/join)申请成为应用市场开发者。申请时需要填写开发者资料，并阅读和同意当前开发者协议。申请通过后，你可以在[应用管理页面](https://www.halo.run/uc/developer/apps)创建和管理自己的应用。 +上架应用前，你需要使用已完成邮箱验证的 Halo 官网账号，在[开发者入驻页面](https://www.halo.run/uc/developer/join)申请成为应用市场开发者。申请时需要填写开发者资料，并阅读和同意当前开发者协议。 + +申请通过后，可以在[应用管理页面](https://www.halo.run/uc/developer/apps)创建和管理自己的应用。如果申请被驳回，可以根据审核意见修改资料后重新提交。待审核的开发者申请可以取消，取消后也可以重新提交。 -如果申请被驳回，可以根据审核意见修改资料后重新提交。待审核的开发者申请可以取消，取消后也可以重新提交。 +## 创建应用和首个版本 -## 首次上架流程 +### 创建应用 -首次上架应用需要经过应用级审核。建议按以下顺序准备： +在[应用管理页面](https://www.halo.run/uc/developer/apps)创建应用时，需要填写应用类型、名称、简介、Logo、截图、README、许可证、外部链接、开源仓库或支持地址等信息。 -1. 在[应用管理页面](https://www.halo.run/uc/developer/apps)创建应用，填写应用类型、名称、简介、Logo、截图、README、许可证、外部链接、开源仓库或支持地址等上架信息。 -2. 创建首个版本，填写版本号、Halo 兼容范围和版本说明。版本号应符合 Semantic Versioning 规范，Halo 兼容范围应是合法的 Semantic Versioning range。 -3. 上传版本制品。插件通常应上传可安装的 JAR 包，主题通常应上传可安装的 ZIP 包。 -4. 对照[应用市场审核指南](./app-review-guidelines.md)完成提交前自查。 -5. 提交审核，阅读并同意应用上架协议；如应用需要测试账号、演示环境、特殊安装步骤或重新提交说明，可以在提交说明中补充。 +上架信息应准确反映应用的实际功能、限制和使用成本。涉及隐私、第三方服务、外部授权或商业限制时，应在 README 或相关字段中明确说明。 + +### 创建首个版本 + +创建应用后，需要继续创建首个版本： + +1. 填写版本号。 +2. 填写 Halo 兼容范围。 +3. 填写版本说明。 +4. 上传版本制品。 首次提交审核前，应用应仍处于草稿状态，并且仅保留一个初始草稿版本。该版本至少需要包含一个上传完成的制品。 -## 审核期间 +## 提交首次审核 + +首次上架应用需要经过应用级审核。提交前请先对照[应用市场审核指南](./app-review-guidelines.md)完成自查，重点确认： + +1. 应用可以在声明兼容的 Halo 版本中完成安装、启用、配置、使用、禁用和卸载。 +2. 上架信息、截图、README、版本说明和外部链接真实准确。 +3. 版本号和 Halo 兼容范围格式正确。 +4. 插件 `plugin.yaml` 中的 logo 字段已正确设置，不能继续使用插件开发模板中的默认 Halo 图标。 +5. 主题和插件的描述文件中已正确设置 `homepage`、`issues`、`license` 字段。 +6. 许可证、第三方资源、商标、图片、字体、图标和模板授权清晰。 +7. 应用不包含恶意代码、未披露数据收集、隐藏远程执行、高危安全漏洞或违法违规内容。 + +提交审核时需要阅读并同意应用上架协议。如应用需要测试账号、演示环境、特殊安装步骤或重新提交说明，可以在提交说明中补充。 + +## 审核期间和审核结果 -提交审核后，平台会保存提交当时的应用信息、README、初始版本、版本说明、制品和协议确认信息作为审核快照。审核期间如需修改应用、版本、说明或制品，应取消审核、等待驳回后重新提交，或按审核意见处理。 +提交审核后，平台会保存提交当时的应用信息、README、初始版本、版本说明、制品和协议确认信息作为审核快照。 -审核通过后，应用会发布到应用市场。审核被拒时，审核意见可能引用[应用市场审核指南](./app-review-guidelines.md)中的条款编号，你需要按对应条款整改后重新提交。即使应用已经通过审核，后续版本、重大更新或出现风险、投诉时，仍可能被重新审核、暂停分发或下架。 +审核期间如需修改应用、版本、说明或制品，应取消审核、等待驳回后重新提交，或按审核意见处理。 -## 上架要求 +审核通过后，应用会发布到应用市场。审核被拒时，审核意见可能引用[应用市场审核指南](./app-review-guidelines.md)中的条款编号，你需要按对应条款整改后重新提交。 -在你决定上架到 Halo 应用市场前，请确保已经完成以下要求： +即使应用已经通过审核，后续版本、重大更新或出现风险、投诉时，仍可能被重新审核、暂停分发或下架。 -1. 插件必须正确设置 `plugin.yaml` 中的 logo 字段，不能是插件开发模板中默认的 Halo 图标。 -2. 主题和插件的描述文件中必须正确设置 `homepage`、`issues`、`license` 字段，详细解释： - 1. `homepage`：应用的主页，可以填写为 GitHub 仓库地址或者 Halo 应用市场的应用详情页地址。 - 2. `issues`：应用的反馈地址，可以填写为 GitHub 仓库的 issues 地址。 - 3. `license`：应用的发行许可证。 -3. 应用必须编写介绍和使用文档。 -4. 应用如果是基于其他程序开发的，需要保证许可证兼容。 -5. 应用的截图、说明、外部链接、隐私说明、第三方服务说明和商业限制应真实准确，并与应用实际功能保持一致。 -6. 应用不得包含恶意代码、未披露数据收集、隐藏远程执行、高危安全漏洞或违法违规内容。 +## 发布后维护 -更多审核规则请查阅[应用市场审核指南](./app-review-guidelines.md)。 +### 手动发布后续版本 -## 后续版本和自动发布 +应用首次审核通过后，开发者可以在[应用管理页面](https://www.halo.run/uc/developer/apps)为自己拥有的应用发布后续版本。 -应用首次审核通过后，开发者可以在[应用管理页面](https://www.halo.run/uc/developer/apps)为自己拥有的应用发布后续版本。后续版本仍应符合[应用市场审核指南](./app-review-guidelines.md)，但当前流程不会为每个后续版本创建独立审核记录。 +后续版本仍应符合[应用市场审核指南](./app-review-guidelines.md)。当前流程不会为每个后续版本创建独立审核记录，但开发者仍应确保版本制品、版本说明、兼容范围和上架资料准确可靠。 -如果你希望在 GitHub 发布 Release 后自动同步后续版本到应用市场，可以修改 CI / CD 工作流： +### 分享应用 + +为了让更多 Halo 用户知道你的应用，可以在以下渠道分享： + +1. [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo)：你可以向这个仓库发起 PR 提交应用信息。 +2. [Halo 论坛](https://bbs.halo.run/t/plugins)：你可以在 Halo 官方社区的[插件](https://bbs.halo.run/t/plugins)和[主题](https://bbs.halo.run/t/themes)板块发布应用。 + +### 使用 GitHub Actions 自动构建和发布 + +Halo 的主题和插件可以使用 [halo-sigs/reusable-workflows](https://github.com/halo-sigs/reusable-workflows) 提供的 GitHub Actions 工作流自动构建，并在 GitHub Release 发布时上传制品。 + +首次审核前，建议先让 CD 工作流只上传 GitHub Release 资产，不自动同步到应用市场。应用首次审核通过后，再补充应用 ID 和个人令牌，用于自动同步后续版本。 + +插件 CI 示例： + +```yaml title=".github/workflows/ci.yaml" +name: CI + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + ci: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-ci.yaml@v4 + with: + ui-path: "ui" +``` + +插件 CD 示例，仅上传 GitHub Release 资产： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v4 + permissions: + contents: write + with: + ui-path: "ui" + skip-appstore-release: true +``` + +主题 CD 示例，仅上传 GitHub Release 资产： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v4 + permissions: + contents: write + with: + skip-appstore-release: true +``` + +使用 `theme-cd.yaml` 发布主题时，主题仓库需要使用 pnpm，并在 `package.json` 中提供 `build` 脚本。该脚本需要执行 `npx @halo-dev/theme-package-cli`；如果主题还有其他构建步骤，应先执行这些步骤，再执行主题打包命令。 + +```json title="package.json" +{ + "scripts": { + "build": "vite build && npx @halo-dev/theme-package-cli" + } +} +``` + +### 自动同步后续版本到应用市场 + +应用首次审核通过后，如果希望在 GitHub 发布 Release 时自动同步后续版本到应用市场，可以调整 CD 工作流： 1. 移除 `skip-appstore-release: true` 配置，或者设置为 `false`。 2. 在 `with` 中添加 `app-id` 配置，值为应用市场的应用 ID，可在[应用管理页面](https://www.halo.run/uc/developer/apps)查看。 -3. 在 Halo 官网的个人中心创建一个新的[个人令牌](https://www.halo.run/uc/profile?tab=pat)，勾选 **应用市场开发者 > 版本管理**。 +3. 在 Halo 官网的个人中心创建新的[个人令牌](https://www.halo.run/uc/profile?tab=pat)，勾选 **应用市场开发者 > 版本管理**。 4. 在 GitHub 仓库的设置 -> `Secrets and variables` 中新建一个 Secret，名称为 `HALO_PAT`，值为你在 Halo 官网创建的个人令牌。 +5. 在工作流中将 `HALO_PAT` 映射为 reusable workflow 需要的 `halo-pat`。 + +插件 CD 示例，自动同步到应用市场： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v4 + secrets: + halo-pat: ${{ secrets.HALO_PAT }} + permissions: + contents: write + with: + app-id: app-xxxxxxxx + ui-path: "ui" +``` + +主题 CD 示例，自动同步到应用市场： + +```yaml title=".github/workflows/cd.yaml" +name: CD + +on: + release: + types: + - published + +jobs: + cd: + uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v4 + secrets: + halo-pat: ${{ secrets.HALO_PAT }} + permissions: + contents: write + with: + app-id: app-xxxxxxxx +``` + +以上插件示例假设 UI 子项目路径为 `ui`；如果你的仓库使用默认的 `console` 路径，可以移除 `ui-path`，或按实际结构调整。若项目使用 Corepack 并且已在 `package.json` 中定义 `packageManager`，可以参考 `halo-sigs/reusable-workflows` 的说明调整 `pnpm-version`。 diff --git a/versioned_docs/version-2.25/developer-guide/appendix/publish-app.md b/versioned_docs/version-2.25/developer-guide/appendix/publish-app.md deleted file mode 100644 index bf5a85c9..00000000 --- a/versioned_docs/version-2.25/developer-guide/appendix/publish-app.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: 发布应用 -description: 了解如何与我们的社区分享你的主题和插件 ---- - -了解如何与我们的社区分享你的主题和插件，下文以应用统称主题和插件。 - -## GitHub 托管 - -如果你的应用是一个开源应用，那么我们推荐将其托管在 GitHub 上，可以获得以下好处： - -1. 可以利用 GitHub 的 CI/CD 功能，实现自动构建和版本发布。 -2. 可以通过 GitHub 的 Issues 功能跟踪用户反馈。 -3. 可以获得更多用户关注和贡献。 - -除此之外，我们推荐为 GitHub 仓库添加与 Halo 相关的 [Topics](https://github.com/topics)，以便让更多用户找到你的应用，比如主题可以添加 [#halo-theme](https://github.com/topics/halo-theme)，插件可以添加 [#halo-plugin](https://github.com/topics/halo-plugin)。 - -## 版本发布 - -当你完成了你的应用并进行充分测试后，就可以在 GitHub 上创建新的 Release，其中版本规范可以参考[版本控制](#version-control)。 - -### 集成 CI / CD - -我们为 Halo 的主题和插件提供了适用于 GitHub Action 的 CI / CD [工作流](https://github.com/halo-sigs/reusable-workflows)，可以非常方便的集成到你的 GitHub 仓库中，以下是示例： - -插件 CI： - -```yaml title=".github/workflows/ci.yaml" -name: CI - -on: - push: - branches: - - main - pull_request: - branches: - - main - -jobs: - ci: - uses: halo-sigs/reusable-workflows/.github/workflows/plugin-ci.yaml@v3 - with: - ui-path: "ui" - pnpm-version: 9 - node-version: 22 - java-version: 21 -``` - -插件 CD： - -此工作流会在每次发布 Release 时自动执行，会自动构建插件并上传产物到 Release 的 Assets 中。 - -```yaml title=".github/workflows/cd.yaml" -name: CD - -on: - release: - types: - - published - -jobs: - cd: - uses: halo-sigs/reusable-workflows/.github/workflows/plugin-cd.yaml@v3 - permissions: - contents: write - with: - pnpm-version: 9 - node-version: 22 - java-version: 21 - skip-appstore-release: true -``` - -主题 CD： - -此工作流会在每次发布 Release 时自动执行，会自动构建主题并上传产物到 Release 的 Assets 中。 - -```yaml title=".github/workflows/cd.yaml" -name: CD - -on: - release: - types: - - published - -jobs: - cd: - uses: halo-sigs/reusable-workflows/.github/workflows/theme-cd.yaml@v3 - permissions: - contents: write - with: - skip-appstore-release: true - node-version: 22 - pnpm-version: 9 -``` - -关于 CI / CD 的更多详细信息，可查阅：[halo-sigs/reusable-workflows](https://github.com/halo-sigs/reusable-workflows) - -## 分享应用 - -为了方便让 Halo 的用户知道你的应用，可以在以下渠道分享： - -1. [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo)：你可以向这个仓库发起一个 PR 提交你的应用信息。 -2. [Halo 论坛](https://bbs.halo.run/t/plugins)：你可以在 Halo 官方社区的[插件](https://bbs.halo.run/t/plugins)和[主题](https://bbs.halo.run/t/themes)板块发布你的应用。 - -## 发布到应用市场 - -Halo 官方应用市场支持开发者自助创建应用并提交首次上架审核。具体流程请查阅[应用市场 / 发布应用](../app-store/publish-app.md)，提交前请对照[应用市场审核指南](../app-store/app-review-guidelines.md)完成自查。 - -## 版本控制 {#version-control} - -为了保持 Halo 生态系统的健康、可靠和安全，每次你对自己拥有的应用进行重大更新时，我们建议在遵循 [semantic versioning spec](http://semver.org/) 的基础上发布新版本。遵循语义版本控制规范有助于其他依赖你代码的开发人员了解给定版本的更改程度，并在必要时调整自己的代码。 diff --git a/versioned_docs/version-2.25/developer-guide/plugin/interaction/dependency.md b/versioned_docs/version-2.25/developer-guide/plugin/interaction/dependency.md index 6aebd335..b16b9e6d 100644 --- a/versioned_docs/version-2.25/developer-guide/plugin/interaction/dependency.md +++ b/versioned_docs/version-2.25/developer-guide/plugin/interaction/dependency.md @@ -328,4 +328,4 @@ jobs: API 模块和插件模块的版本应该保持一致，以确保插件在不同环境中的一致性。 -版本的发布应该遵循 [语义化版本规范](../../appendix/publish-app.md#version-control)，以确保插件的版本号能够清晰地表达插件的变化和向后兼容性。 +版本的发布应该遵循 [语义化版本规范](../../app-store/publish-app.md#version-control)，以确保插件的版本号能够清晰地表达插件的变化和向后兼容性。 diff --git a/versioned_sidebars/version-2.25-sidebars.json b/versioned_sidebars/version-2.25-sidebars.json index 4d399499..a005557e 100644 --- a/versioned_sidebars/version-2.25-sidebars.json +++ b/versioned_sidebars/version-2.25-sidebars.json @@ -449,16 +449,6 @@ ] }, "developer-guide/form-schema", - "developer-guide/annotations-form", - { - "type": "category", - "label": "附录", - "link": { - "type": "generated-index" - }, - "items": [ - "developer-guide/appendix/publish-app" - ] - } + "developer-guide/annotations-form" ] }