在發行流程中執行 backport 建置工具

這是建置工具，而非執行階段依賴。本頁說明如何操作產生 backport 的發行流程。此流程在 CI 中執行；絕不會在下游應用程式中執行。

概覽

正式環境流程使用兩個工作流程。0-ci.yml 會為任一永久分支的每一項變更把關。build.yml 會產生並發行散布套件，並由來源發行觸發。兩者皆可對照 .github/workflows/ 驗證。

CI 把關

0-ci.yml 會在推送至 PHP74 與 PHP81，以及對這兩個分支發出 pull request 時執行。它包含三個依序執行的工作：

PHPStan（建置工具）——composer analyse，對 rector/rules 與 scripts 執行 level 10。
PHPUnit（Rector 規則）——composer test，也就是三條自訂規則的 fixture 測試套件。
建置試跑——composer build:dry，必須通過前兩個工作才會執行。

受信任的事件會在自架的 PHP runner 上執行。來自 fork 的 pull request 與 Dependabot 會在已佈建 PHP 8.5 的 GitHub 託管 runner 上執行。請對照 0-ci.yml 驗證（也就是 runs-on 運算式與條件式 setup-php 步驟）。雙分支模型會透過各分支各自的 pull request，分別把關同時觸及兩個目標的變更。

發行流程

build.yml 是正式建置流程。它會在類型為 source-release 的 repository_dispatch 事件發生時觸發，也可透過附帶標籤輸入的 workflow_dispatch 手動觸發。版本標籤會驅動整個流程。版本號是根據已宣告的公開 API 所定義的 MAJOR.MINOR.PATCH（Semantic Versioning 2.0.0 §2）。

PHP 8.1 通道

build-php81——簽出建置工具，佈建 PHP 8.5，安裝建置依賴，於發行標籤複製來源儲存庫，執行 scripts/build.php，將 runner 切換至 PHP 8.1，在 PHP 8.1 上對 output/src 執行語法檢查，接著以 --no-dev 安裝所產生的套件。輸出會以成品形式上傳。
validate-php81——下載成品，並在 PHP 8.1、8.2、8.3 與 8.4 矩陣上安裝與測試。
release-php81——下載成品，提交所產生的檔案樹並加上標籤，將其打包成 zip（排除 vendor/ 與 .git/），並發布附帶該封存檔的 GitHub release。

PHP 7.4 通道

build-php74——在 PHP74 分支上簽出建置工具，佈建 PHP 8.5，僅於標籤複製核心來源儲存庫，執行 scripts/build.php --target=php74，切換至 PHP 7.4，並在 PHP 7.4 上對輸出執行語法檢查。
validate-php74——在 PHP 7.4 與 8.0 矩陣上安裝與測試。
release-php74——將僅含核心的輸出打包成 zip，並作為第二個封存檔附加到同一個 release。

請對照 build.yml 的工作定義與矩陣驗證。

這兩個通道共用同一個 GitHub release。PHP 8.1 通道負責建立 release，而 PHP 7.4 通道則將自己的封存檔附加到同一個標籤。搭配 cancel-in-progress: false 的 concurrency 群組 backport-build 會將建置序列化，避免兩次來源發行互相競爭。

操作流程

觸發建置

來源組織發布 release 時，建置通常會自動觸發。若要手動重新建置特定標籤，請以標籤輸入派送 build.yml（例如 v2.0.0）。派送權杖是 secrets.BACKPORT_TRIGGER_TOKEN，用來授權複製來源儲存庫。請對照 build.yml 驗證（workflow_dispatch.inputs.tag、GH_TOKEN）。

解讀失敗的建置

建置指令稿會在第一個失敗階段停止，並印出階段名稱與錯誤。這五個階段分別是合併、Rector、composer.json 產生、資產複製與驗證。若建置後的語法檢查步驟失敗，表示 Rector 產生了目標執行階段拒絕的輸出。該步驟就是保護發行的把關。請參考 /integrations/backport/troubleshooting/，將該失敗對應到其成因。

會發布哪些內容

該 release 會附加已壓縮成 zip 的散布封存檔。此套件會以版本標籤形式發布，而非以分支形式發布。使用者會從該發行管道安裝 nextpdf/backport（並視需要選用 nextpdf/backport-pro）。該封存檔會排除 vendor/ 與 .git/。請對照 build.yml 驗證（zip -r ... -x '*/vendor/*' '*/.git/*'）。

為輸出設定版本

所產生的 composer.json 會帶有透過命令列傳入的版本（--version，或是移除開頭 v 後的派送標籤）。Pro 套件會將 nextpdf/backport 釘選在相符的 major.minor caret 版本限制上。請對照 scripts/adjust-composer.php 驗證（majorMinor()、generateProComposer()）。請讓來源發行標籤與 backport 版本保持一致，使 replace 對應表維持一致。

後續

/integrations/backport/security-and-operations/ —— 此流程的信任邊界與供應鏈態勢。
/integrations/backport/troubleshooting/ —— 逐階段的失敗參考。