發布新版

進階

把測試過的建置變成新版。這一頁是給維護者的。

開始之前

測試裡的每一項檢查都通過，包括完整的端對端執行，以及長時間和 fault 的執行。
CHANGELOG.md 裡有新的版本。
已安裝 Python 3，供發布用的腳本使用。

準備新版

撰寫 releases/notes-<version>.toml，例如 releases/notes-1.0.0.toml。見新版說明檔。
檢查它：
Terminal window
```
python deploy/release/notes.py 1.0.0 --check
```
你應該不會看到錯誤。出現禁用字詞、破折號、日期、上線宣傳用語，或重複的亮點，都會以代碼 1 結束。
產生新版的文字：
Terminal window
```
python deploy/release/notes.py 1.0.0
```
你應該會在 releases/out/1.0.0/ 裡找到 7 個檔案。
建置 image，並用全新的設定資料夾啟動它：
Terminal window
```
docker build --file deploy/Dockerfile .
```
你應該會看到首次執行的設定精靈。
在你的電腦上執行測試裡的每一項檢查。測試在本機執行，不在 GitHub 上執行。
把版本號交給維護者。維護者會在 main 上推送版本 tag，這樣就會啟動發布。

選項

版本與 tag 名稱

項目	名稱
Git tag（由維護者推送）	`1.0.0`（純數字，不加 v）
Image tag 和說明檔的 `version`	`1.0.0`

工作流程只會在 X.Y.Z 格式的 tag 上啟動，而且當 tag 和 VERSION 檔案不一致時就會停止。

Image tag

每個新版都會推送它的版本 tag 和 :latest。

收回新版

推送帶有修正的下一個版本。
在更新清單裡標記有問題的版本，這樣已安裝的 App 就不會提示更新到它。
保留這個 tag。

如果沒有成功

症狀。 notes.py --check 以代碼 1 結束。 原因。 說明檔違反了某條規則。訊息會指出是哪一行。 解決方式。 編輯說明檔，絕不要改 releases/out 裡的檔案，然後再執行一次。

症狀。 工作流程停在 VERSION says。 原因。 tag 和 VERSION 檔案不一致。 解決方式。 在 main 上修正 VERSION，並推送下一個版本 tag。

給進階使用者

新版說明檔

每份新版文字都來自同一個檔案。絕不要手動編輯它產生的內容。

欄位	內容
`version`	純 `X.Y.Z`
`theme`	一行
`images`	`{registry, name}` 的清單。只有 Docker Hub 的 `holyarrs/holyarrs`
`docs_url`	選用。留空代表沒有文件連結
`[[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`	App 顯示的說明
`reddit.txt`	Reddit 貼文
`discord-dm.txt`、`discord-announce.md`	Discord。每個都要少於 1,000 個字元
`roadmap-card.json`	路線圖卡片

notes.py 接受 --file（另一個說明檔）、--map（另一份 credits 對照表）、--out（另一個輸出資料夾）和 --date。--check 會對過長的行和近乎重複的內容發出警告。

Image 工作流程

推送版本 tag 時，HolyArrs - Release 工作流程就會啟動。它有三個步驟：

為 linux/amd64、linux/arm64 和 linux/arm/v7 建置並推送 image，附上版本 tag 和 latest。
用 README.md 更新 Docker Hub 的說明。
用這個版本在 CHANGELOG.md 裡的段落發布 GitHub release。

更新清單

App 會讀取已簽署的更新清單。每個新版都會加入它的條目並簽署。簽署金鑰絕不放進 repo。HolyArrs 會拒絕它無法驗證的清單。

發布之後，檢查 image 的版本標籤和 tag 一致，並在第一天留意新的 issue：

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

Unraid 測試範本

deploy/release/nas-template.py 會為某一個確切的 image 寫出 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`	registry 的 manifest digest，不是 Docker image ID
`--config`	一個 pool 路徑。這個工具會拒絕 `/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 > 新增 container > 範本）底下選它。