# =============================================================================
# 用途: calculate-version 專案的 CI workflow。
#       在 Pull Request 開啟或更新 (且目標分支非 master) 時,先以 composite
#       action 釋出並標註 beta 成品版本,再用剛標註出的版本呼叫
#       calculate-version action 計算版本號。
# 更新日期: 2026/06/30 17:18:23
# =============================================================================

# workflow 名稱,顯示於 Gitea Actions 介面。
name: CI
# 觸發條件設定,定義此 workflow 在哪些事件下被啟動。
on:
  # 於 Pull Request 事件觸發。
  pull_request:
    # 忽略目標分支為 master 的 PR (master 走 CD 流程,不在此 CI 審查)。
    branches-ignore:
    # 排除清單的單一項目: master 分支。
    - master
    # 僅在 PR 開啟 (opened) 或有新 commit 推送 (synchronize) 時觸發,避免其他 PR 事件 (如關閉) 重複觸發。
    types: [opened, synchronize]
# 定義此 workflow 要執行的所有 job。
jobs:
  # 第一個 job: 釋出並標註成品版本,並將版本號往外拋給後續 job 使用。
  release-tag-version:
    # job 顯示名稱。
    name: Release Tag Version
    # 指定執行環境 (runner) 標籤為 ubuntu。
    runs-on: ubuntu
    # 宣告此 job 的輸出,供後續 needs 此 job 的其他 job 取用。
    outputs:
      # 將下方 id 為 release-tag-version 的 step 所輸出的 version,設為此 job 的對外 version 輸出 (關鍵點: 透過 outputs 把標註出的版本往外拋)。
      version: ${{ steps.release-tag-version.outputs.version }}
    # 此 job 依序執行的步驟。
    steps:
    # 步驟: 呼叫 composite action 進行釋出並標註成品版本。
    - name: 釋出並標註成品版本
      # 設定此 step 的 id,讓上方 outputs 可用 steps.release-tag-version.outputs.version 取得其輸出。
      id: release-tag-version
      # 引用 release-tag-version composite action,版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選 (集中於 repo/org 變數管理,便於統一升版)。
      uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
      # 傳遞給該 action 的輸入參數。
      with:
        # is_beta 設為 true 表示走 beta 標版流程 (標註的是 beta 成品版本,而非正式版)。
        is_beta: true
  # 第二個 job: 以前一個 job 標註出的版本來計算版本號。
  calculate-version:
    # job 顯示名稱。
    name: Calculate Version
    # 指定執行環境 (runner) 標籤為 ubuntu。
    runs-on: ubuntu
    # 宣告相依於 release-tag-version job: 需等其成功後才執行,並可透過 needs 取得其 outputs (關鍵點: 以此取得剛標註出的版本)。
    needs: release-tag-version
    # 此 job 依序執行的步驟。
    steps:
    # 步驟: 呼叫 calculate-version action 計算版本號。
    - name: 計算版本號
      # 引用本專案的 calculate-version action,並以 @v<version> 釘選自身 action 版本; 其中 version 來自上一個 job 透過 needs 取得的 outputs.version (關鍵點: 用剛標註的版本釘選自身)。
      uses: https://gitea.jsc.idv.tw/docker-actions/calculate-version@v${{ needs.release-tag-version.outputs.version }}