130 lines
5.6 KiB
Markdown
130 lines
5.6 KiB
Markdown
# 向 Trove 官方软件源投稿 / Contributing to the Trove Curio Source
|
||
|
||
<!-- trove:zh:start -->
|
||
|
||
官方软件源是公开索引，不接收 Curio 源码或安装包。外部作者与官方仓库使用同一条发布路径：先在 Curio 仓库发布 Release，再通过 Pull Request 更新本仓库。
|
||
|
||
### 1. 发布 Curio Release
|
||
|
||
Release 必须公开提供：
|
||
|
||
- 一个或多个 `.curio` 安装包；
|
||
- 一个名为 `trove-release.json` 的描述文件；
|
||
- 与 Curio Manifest 相同的通用 SemVer 版本。Tag 可以是版本本身，也可以只多一个 `v` 前缀。
|
||
|
||
描述文件使用 `schemaVersion: 2`，并显式选择本软件源：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 2,
|
||
"repository": "owner/repository",
|
||
"tag": "v1.2.3",
|
||
"commit": "完整的 Git commit SHA",
|
||
"registries": ["trove/curios"],
|
||
"plugins": [
|
||
{
|
||
"id": "dev.example.curio",
|
||
"name": "Example Curio",
|
||
"description": "一句面向使用者的说明。",
|
||
"icon": "https://example.com/curio.png",
|
||
"version": "1.2.3",
|
||
"engine": { "trove": ">=0.0.1-alpha.1 <0.0.2" },
|
||
"artifacts": [
|
||
{
|
||
"target": "aarch64-apple-darwin",
|
||
"asset": "dev.example.curio-1.2.3-aarch64-apple-darwin.curio",
|
||
"sha256": "64 位小写十六进制 SHA-256",
|
||
"size": 123456
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
版本只按通用 SemVer 校验，不要求使用某条特定预发布版本线。开发阶段的预发布版本允许重建并替换同名安装包；稳定版本发布后不可覆盖，需要修正时发布新版本。
|
||
|
||
### 2. 更新索引
|
||
|
||
PR 只修改 [`source/index.json`](https://git.render.ink/trove/curios/src/branch/main/source/index.json)，以及可选的单个 Curio 图标：
|
||
|
||
- `repository` 填写公开的 HTTP(S) 仓库地址；
|
||
- `descriptor` 指向该 Release 的 `trove-release.json`；
|
||
- `url` 指向公开可下载的 Release 安装包；
|
||
- `size` 和 `sha256` 必须由最终安装包计算；
|
||
- Curio 按 ID 排序，版本按 SemVer 从新到旧排序，产物按 target 排序。
|
||
|
||
图标属于 Curio，不属于版本。可以使用公开的 HTTP(S) 图片地址；也可以提交一次 `source/icons/<curio-id>.png` 或 `.webp`，大小不超过 256 KiB，并在所有版本中复用同一个 URL。不要提交 Base64 图标。
|
||
|
||
### 3. 身份与审核
|
||
|
||
首次收录会人工确认 Curio 的名称、用途、仓库和发布者意图。通过后，Curio ID 会与该仓库永久绑定；稳定版本的 `(id, version, target)` 不可覆盖，预发布版本允许由同一绑定仓库重建。仓库迁移需要单独审核，不能夹在版本 PR 中。
|
||
|
||
后续版本仍会从上游 Release 重新读取描述文件和安装包，核对仓库、版本、显式软件源授权、大小与 SHA-256。校验全部通过的已绑定仓库版本可以自动合并；校验失败的 PR 不能合并。
|
||
|
||
<!-- trove:zh:end -->
|
||
|
||
<!-- trove:en:start -->
|
||
|
||
The official source is a public index; it does not host Curio source code or packages. Third-party and official repositories follow the same path: publish a Release in the Curio repository, then update this repository through a pull request.
|
||
|
||
### 1. Publish a Curio Release
|
||
|
||
The public Release must contain:
|
||
|
||
- one or more `.curio` packages;
|
||
- a descriptor named `trove-release.json`;
|
||
- a generic SemVer matching the Curio manifest. The tag may be the version or the version with one leading `v`.
|
||
|
||
The descriptor uses `schemaVersion: 2` and explicitly opts in to this source:
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 2,
|
||
"repository": "owner/repository",
|
||
"tag": "v1.2.3",
|
||
"commit": "full Git commit SHA",
|
||
"registries": ["trove/curios"],
|
||
"plugins": [
|
||
{
|
||
"id": "dev.example.curio",
|
||
"name": "Example Curio",
|
||
"description": "A short user-facing description.",
|
||
"icon": "https://example.com/curio.png",
|
||
"version": "1.2.3",
|
||
"engine": { "trove": ">=0.0.1-alpha.1 <0.0.2" },
|
||
"artifacts": [
|
||
{
|
||
"target": "aarch64-apple-darwin",
|
||
"asset": "dev.example.curio-1.2.3-aarch64-apple-darwin.curio",
|
||
"sha256": "64 lowercase hexadecimal SHA-256 characters",
|
||
"size": 123456
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Versions are checked as generic SemVer and are not tied to a particular prerelease line. Prerelease assets may be rebuilt in place during development; stable Release assets are immutable and require a new version for corrections.
|
||
|
||
### 2. Update the index
|
||
|
||
A PR changes only [`source/index.json`](https://git.render.ink/trove/curios/src/branch/main/source/index.json) and, optionally, one stable Curio icon:
|
||
|
||
- `repository` is the public HTTP(S) repository URL;
|
||
- `descriptor` points to that Release's `trove-release.json`;
|
||
- `url` points to a publicly downloadable Release asset;
|
||
- `size` and `sha256` are calculated from the final package;
|
||
- Curios are sorted by ID, versions by descending SemVer, and artifacts by target.
|
||
|
||
An icon belongs to a Curio, not a version. Use a public HTTP(S) image URL, or add one `source/icons/<curio-id>.png` or `.webp` file up to 256 KiB and reuse its URL across releases. Do not embed Base64 icons.
|
||
|
||
### 3. Identity and review
|
||
|
||
The first submission is manually reviewed for its name, purpose, repository, and publisher intent. Once accepted, the Curio ID is permanently bound to that repository. Stable `(id, version, target)` entries are immutable; prerelease entries may be rebuilt only by the bound repository. Repository transfers require a separate review.
|
||
|
||
Later versions are verified again from the upstream Release: repository, version, explicit registry opt-in, byte size, and SHA-256 must all match. A verified update from a bound repository may merge automatically; a failing PR cannot merge.
|
||
|
||
<!-- trove:en:end -->
|