发布版本

把一个测试过的构建变成正式版。这一页是写给维护者的。

警告

只有维护者可以启动发布。不要自己打标签、发布，或者移动镜像标签。

开始之前

• 测试里的每项检查都通过，包括一次完整的端到端测试，以及长时间测试和故障测试。
• CHANGELOG.md 里已经有新版本。
• 已安装 Python 3，发布脚本要用。

准备发布

1. 编写 releases/notes-<version>.toml，例如 releases/notes-1.0.0.toml。见发布说明文件。

2. 检查它：

   python deploy/release/notes.py 1.0.0 --check

   你应该不会看到任何错误。出现禁用词、破折号、日期、上线宣传的说法，或者亮点里的 issue 重复，都会以 1 退出。

3. 生成发布文本：

   python deploy/release/notes.py 1.0.0

   你应该会在 releases/out/1.0.0/ 里看到 7 个文件。

4. 构建镜像，并用一个全新的配置文件夹启动它：

   docker build --file deploy/Dockerfile .

   你应该会看到首次运行的设置向导。

5. 在你的机器上运行测试里的每项检查。测试在本地跑，不在 GitHub 上跑。

6. 把版本交给维护者。维护者在 main 上推送版本标签，发布就从这里开始。

选项

版本和标签的名字

东西	名字
Git 标签（由维护者推送）	1.0.0（纯数字，不带 v）
镜像标签和说明文件里的 version	1.0.0

工作流只对 X.Y.Z 形式的标签启动，标签和 VERSION 文件不一致时会停下。

镜像标签

每次发布都会推送它的版本标签和 :latest。

撤回一个版本

1. 推送带修复的下一个版本。
2. 在更新列表里标记有问题的版本，这样各个安装就不会再提供它。
3. 保留标签。

如果不成功

现象。 notes.py --check 以 1 退出。 原因。 说明文件违反了某条规则。提示信息里写了是哪一行。 解决办法。 改说明文件，绝不要改 releases/out 里的文件，然后再运行一次。

现象。 工作流停下，并显示 VERSION says。 原因。 标签和 VERSION 文件不一致。 解决办法。 在 main 上改好 VERSION，再推送下一个版本标签。

进阶

发布说明文件

所有发布文本都出自同一个文件。绝不要手工改它生成的东西。

字段	内容
version	纯 X.Y.Z
theme	一行
images	{registry, name} 的列表。只有 Docker Hub 的 holyarrs/holyarrs
docs_url	可选。留空表示没有 Docs 链接
[[highlights]]	正好 3 条，每条带 line、issues 和 shot。它们的 issue 不会出现在任何分组的行里
[groups]	按位置分组的行。默认是 New。其他的以 Changed: 、Fixed: 或 Docs: 开头。每行以它的 issue 结尾，比如 (#46)。不足 3 行的位置会归到 Also new 下面
可选	[before_you_update]（breaking、manual_steps、backup、rollback）、security、known_issues、credits、[stats]。空的部分会被隐藏

GitHub 登录名只有在确知时才用，写在说明文件或 releases/credits-map.json 里。

正文顺序：theme、Highlights、各个位置（Requests、Library、Downloads、Indexers、Accounts、Health、Setup、Install）、Also new、Security、Known issues、Before you update、Image、Thanks、统计行。

releases/out/<version>/ 里的输出	用途
changelog.md	更新日志条目
github.md	GitHub release 正文
update-notes.json	应用里显示的说明
reddit.txt	Reddit 帖子
discord-dm.txt、discord-announce.md	Discord。每个都不超过 1,000 个字符
roadmap-card.json	路线图卡片

notes.py 接受 --file（换一个说明文件）、--map（换一个致谢映射）、--out（换一个输出文件夹）和 --date。--check 会对过长的行和近似重复的内容给出警告。

镜像工作流

推送版本标签时，HolyArrs - Release 工作流就会启动。它有三步：

1. 为 linux/amd64、linux/arm64 和 linux/arm/v7 构建并推送镜像，带版本标签和 latest。
2. 用 README.md 更新 Docker Hub 上的说明。
3. 用 CHANGELOG.md 里这个版本的那一节发布 GitHub release。

更新列表

应用读取一份签名的更新列表。每次发布都会加上自己的条目并签名。签名密钥绝不放进仓库。HolyArrs 会拒绝它无法验证的列表。

发布之后，检查镜像的版本标记和标签是否一致，并在第一天留意新的 issue：

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' holyarrs

Unraid 测试模板

deploy/release/nas-template.py 为一个确切的镜像写出一份 Unraid 用户模板。它不拉取、不安装，也不发布任何东西。

python deploy/release/nas-template.py --image 'holyarrs/holyarrs@sha256:<digest>' --config '/mnt/<pool>/appdata/holyarrs-test' --movies /mnt/user/holyarrs-test-data/movies --downloads /mnt/user/holyarrs-test-data/downloads --port 6262 --output holyarrs-test.xml

把 <digest> 和 <pool> 换成你的值。

参数	说明
--image	镜像仓库的 manifest 摘要，不是 Docker 镜像 ID
--config	一个存储池路径。工具会拒绝 /mnt/user 和 /mnt/user0
--movies、--tv、--music、--downloads	可选。不同的路径是不同的挂载点，所以导入时会复制
--port	默认 6262
--allowed-hosts	可选，用逗号分隔的主机名
--output	要写出的 XML 文件

模板会设置 PUID=99、PGID=100 和 UMASK=022。给这个账户测试媒体的写入权限。把文件放到 /boot/config/plugins/dockerMan/templates-user/，然后在 Docker > Add Container > Template（Docker > 添加容器 > 模板）下选它。

相关页面

• 测试
• 参与贡献
• 更新