gazenot

勿凝视深渊，以免成为发布工程师

Gazenot 是访问 Abyss 的客户端库，Abyss 是 axo Releases 的核心。

axo Releases：解释

Abyss 最容易理解为预构建二进制的简单包注册处。

目标

设计有几个目标

• 应该容易“部分”运行“发布”，以便让最终用户测试他们的发布过程（通过 cargo-dist 的 pull-request CI）
• 应该容易“回滚”过程中失败的部分发布（例如，因为 npm publish 失败）
• 一旦发布真正完成（“宣布”），它应该默认不可变
• 创造比 GitHub 发布更好的东西
• 某些某些软件物料清单功能

核心概念

Abyss 定义以下核心概念

• 包 是一组工件集、发布和公告。它通常与 Cargo 包等东西一一对应。通常，包将是“应用程序”（可能包含多个二进制文件），但也可以是“库”（在这种情况下，它主要存在以托管更改日志/公告/源代码压缩包）。包属于所有者。
• 工件集 实质上是与包相关联的文件目录。它创建时为空，并具有永久随机生成的集合 URL。可以自由增量地将其上传到其中，直到它“升级”到类似发布的版本，此时不应（默认情况下）允许修改。如果工件集未“升级”，则它将成为孤儿，并可在许多天后进行垃圾收集。
• 有 3 个 类似发布（尽管目前只定义了第一个）。一旦创建，类似发布“密封”了工件集以防止修改，并获得更好的工件下载 URL。
  • 发布 是（在工件集之上）具有版本和标签的层。创建发布创建一个发布 URL。一旦最初创建，发布仍然与包的实际发布列表“断开连接”，这对于请求“列出所有发布”或“宣布所有发布”等请求是重要的。有关为什么这很重要的原因，请参阅管道。
  • (理论上)一个 发布预览 是一个模拟发布，它有一个发布预览 URL（而不是正式的发布 URL），允许用户在方便的时候检查发布的內容。原则上，可以在稍后“升级”到真实发布，以避免用户准备宣布时重建/延迟。不清楚这个的范围。
  • (理论上)一个 PR 预览 是一个更简化的发布预览（可能是带有 PR 预览 URL），用于测试拉取请求（如 Vercel）。概念上，这就像“使用 docker 映像托管一个网页”。
• 公告 是（在多个发布之上）的一个层次，应该使用 markdown 主体将其“真正发布”。为发布创建一个公告会使它出现在“列出所有发布”和“最新发布是什么”查询中。值得注意的是，这可以修改最新发布 URL。理论上，这也可能触发“发送通知电子邮件”（GitHub 发布功能）和“发布到社交媒体”，但其中一些可能是“cargo-dist 做的事情”，而不是“Abyss 做的/触发的”。

以下是一些不那么核心但仍然基本的概念

• 所有者（例如，“axodotdev”）是拥有包存储库（这是主要由 Sunfish 管理的）的 SourceHost 的用户（或组织）。我们只是忠实地记录它告诉我们的有关所有权/身份验证的事情
• 源主机（例如，“github”）是包源代码的托管（存储库）提供者

管道

cargo-dist 定义了发布/宣布包的管道，Abyss 在很大程度上模拟了它。cargo-dist 管道是

• 计划：确定我们的托管方式/托管是否工作
• 构建：构建二进制文件/安装程序
• 托管：将文件上传到托管（那就是 Abyss Baybee！！！）
• 发布：发布到各种包管理器
• 宣布：宣布发布

将主机、发布和宣布分离成单独的步骤的目的是为了让我们能够在需要用于像从我们的托管中获取的 npm 包这样的东西时，获得稳定/漂亮的发布 URL。也就是说，通过保持发布“断开”或“权限：只有具有此 URL 的人才能查看”，我们仍然能够在不更新最新发布 URL 或所有发布列表的情况下回滚发布。

注意 1：目前 cargo-dist 在生成安装程序实现时总是将更丑陋的 Set URL 烘焙进去，因为 Abyss 的当前设计不允许 cargo-dist 在实际调用 create-release 之前知道发布 URL，尽管 cargo-dist 从一开始就知道它想要它。尽管如此，这种更丑陋的模式对于发布预览 -> 发布工作流是必要的，所以它工作得很好！

注意 2：目前还没有支持执行此类“发布回滚”的功能。用户需要手动干预，抛出一个断开连接的发布，目前这就像，给我们发电子邮件。关键是，从 概念上 来说，一个断开连接的发布可以被完全废弃（使其发布 URL 失效），而一个已宣布的发布则理想上是尽可能长久。

以下图表描述了 Abyss 的概念如何映射到这个管道（以及 cargo-dist 在每个步骤中调用的端点）。

flowchart LR
    subgraph plan
      create-artifact-set
      check-auth["check-auth\n(technically feeds to Build too\nwith fake URLs, but not host)"]
    end
    subgraph build["build (not modeled by Abyss)"]
        fake2([build apps\nbuild installers\n...])
    end
    subgraph host
      upload-file["upload-file\n(many times)"]
      create-release
      create-release-preview
      create-pr-preview
    end
    subgraph publish["publish (not modeled by Abyss)"]
        fake1([publish to crates.io\npublish to npm\npublish to homebrew\n...])
    end    
    subgraph announce
    F[create-announcement]
    end
    create-artifact-set --> build
    build --> upload-file
    upload-file --> create-release
    upload-file --> create-release-preview
    upload-file --> create-pr-preview
    create-release-preview --> create-release
    create-release --> publish
    publish --> announce

（可以说是 create-release 是“第一个发布步骤”，但 cargo-dist 目前将其归入“托管”，这感觉越来越正确/简单 耸肩...）

工件下载 URL

Abyss 的核心副作用之一是制作可以从其下载的 URL。因为它将发布过程分解成多个阶段，所以有许多种类的工件下载 URL。这些都指向 CDN 托管，而不是 Abyss。

• 一个 设置 URL (https://myuser.artifacts.axodotdev.host/myapp/ax_UJl_tKCujZwxKL1n_K7TM) 是一个用于从 ArtifactSet 下载文件的永久随机生成 URL。它可以嵌入由 cargo-dist 制作的 curl-sh 安装程序的体中，但理想情况下，它 不应该 在像 oranda 网站上出现的 curl-sh 表达式、安装小工具或公告帖子中向最终用户展示。
• 一个 发布 URL (https://myuser.artifacts.axodotdev.host/myapp/v1.0.0/) 是一个用于从 Release 的 ArtifactSet 下载文件的永久稳定格式的 URL。这通常是 curl-sh 表达式 中应展示的内容。如果从未发布 Release，则此 URL 可能会失效。
• 一个 最新（发布）URL (https://myuser.artifacts.axodotdev.host/myapp/latest/) 是一个可变目标稳定格式的 URL，用于下载“任何最新的 Release 的 ArtifactSet”。此 URL 适用于在您不想每次发布时都更新随机文档中链接。
• (理论上) 一个 发布预览 URL ...
• (理论上) 一个 PR 预览 URL ...

许可证

许可协议为以下之一

• Apache License，版本 2.0，(LICENSE-APACHE 或 apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确说明，否则您有意提交的任何贡献，根据 Apache-2.0 许可证的界定，应双重许可如上，无任何额外条款或条件。

如果您有兴趣进行贡献，请阅读我们的 [CONTRIBUTING 指南] 和我们的 [行为准则]。