# 向 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 -->