# =============================================================================
# 指令檔用途：
#   這是一個 Gitea composite action（複合動作），名稱為「Release Tag Version」。
#   它被其他 workflow 引用，用來「自動計算版本號並釋出（release）標註成品版本」。
#   完整流程：
#     (1) 呼叫 calculate-version action 計算本次的版本號。
#     (2) 若版本號非空，組合 release 所需的 name 與 tag_name。
#     (3) 若版本號為空，輸出錯誤訊息並以 exit 1 中止整個 action。
#     (4) 呼叫 akkuman/gitea-release-action 在 Gitea 上建立 release 並打 tag，
#         同時可附帶要釋出的檔案（files）。
#     (5) 呼叫 release-cleanup action 清理舊的成品（release）。
#
# 更新日期：2026/06/26 10:14:14（Asia/Taipei）
# =============================================================================

# action 的顯示名稱，會在 Gitea Actions 介面與被引用時呈現。
name: 'Release Tag Version'
# action 的說明文字，描述此 action 的目的：釋出並標註成品版本。
description: '釋出並標註成品版本'
# action 作者標註，僅作為 metadata，不影響執行行為。
author: 'Jeffery'

# inputs 區塊：定義此 composite action 對外開放、可由呼叫方傳入的參數。
inputs:
  # files 參數：指定要隨 release 一起釋出（上傳）的檔案。
  files:
    # 此參數的描述（原始檔留空）。
    # 需人工確認：description 為空字串，建議補上說明（例如「要釋出的成品檔案路徑或 glob」）以利維護，
    #            但屬文件性質、不影響執行邏輯，故此處不逕自修改。
    description: ''
    # required: false 表示此參數非必填；呼叫方未傳入時，files 會是空值。
    required: false

# runs 區塊：定義此 action 的執行方式與步驟。
runs:
  # using: 'composite' 表示這是「複合動作」，由下方多個 step 串接組成，而非單一 Docker/JS action。
  using: 'composite'
  # steps：依序執行的步驟清單，順序具有意義，不可調換。
  steps:
  # ---------------------------------------------------------------------------
  # Step 1：版本號計算
  #   引用外部 calculate-version action 來計算本次要釋出的版本號，
  #   其結果會以 output「version」提供給後續步驟（透過 step id 取用）。
  # ---------------------------------------------------------------------------
  - name: 版本號計算
    # id 設為 version-calculate，後續步驟以 steps.version-calculate.outputs.version 取得計算結果。
    id: version-calculate
    # uses：引用 Gitea 上 docker-actions/calculate-version action。
    # 版本（@ 後面）由 repository/organization 變數 vars.ACTION_CALCULATE_VERSION 決定，
    # 便於集中管理被引用 action 的版本，不需改動本檔。
    uses: https://gitea.jsc.idv.tw/docker-actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }}

  # ---------------------------------------------------------------------------
  # Step 2：組合釋出參數
  #   僅在版本號非空時執行，組出 release 需要的 name 與 tag_name，
  #   並寫入 GITHUB_OUTPUT 供後續釋出步驟取用。
  # ---------------------------------------------------------------------------
  - name: 組合釋出參數
    # id 設為 release-params，後續步驟以 steps.release-params.outputs.* 取得組好的 name / tag_name。
    id: release-params
    # if 條件：只有當上一步算出的 version 不是空字串時才執行此步驟。
    # 這是「版本有效」的分支，與 Step 3「版本為空」的分支互斥。
    if: ${{ steps.version-calculate.outputs.version != '' }}
    # run：以 shell 執行下列指令來組合參數。
    run: |
      # 取得目前 repository 完整名稱（格式為 owner/repo），存入 repository 變數。
      repository="${{ gitea.repository }}"
      # 取得 Step 1 計算出的版本號，存入 version_value 變數。
      version_value="${{ steps.version-calculate.outputs.version }}"
      # 組出 release 的顯示名稱並寫入 GITHUB_OUTPUT：
      #   ${repository##*/} 為 bash 參數展開，去掉最長前綴「*/」，即取 owner/repo 的最後一段 repo 名稱。
      #   最終格式為「<repo 名稱> v<版本>」（注意 v 前有一個空白）。
      echo "name=${repository##*/} v${version_value}" >> "$GITHUB_OUTPUT"
      # 組出 release 的 tag 名稱並寫入 GITHUB_OUTPUT：格式為「v<版本>」（v 緊接版本，無空白）。
      echo "tag_name=v${version_value}" >> "$GITHUB_OUTPUT"
    # shell: bash 明確指定以 bash 執行（${repository##*/} 等參數展開語法需 bash 支援）。
    shell: bash

  # ---------------------------------------------------------------------------
  # Step 3：檢查版本號輸出
  #   僅在版本號為空時執行；視為錯誤狀況，輸出訊息到 stderr 並中止 action。
  # ---------------------------------------------------------------------------
  - name: 檢查版本號輸出
    # if 條件：只有當 version 為空字串時才執行；與 Step 2 的條件互斥，為「版本無效」分支。
    if: ${{ steps.version-calculate.outputs.version == '' }}
    # run：輸出錯誤訊息並以非零結束碼中止流程。
    run: |
      # 將錯誤訊息寫到 stderr（>&2），表示 calculate-version 沒有產出有效版本號。
      echo "version-calculate output version is empty" >&2
      # 以 exit 1 結束此步驟並讓整個 action 失敗，避免後續用空版本去建立錯誤的 release/tag。
      exit 1
    # shell: bash 明確指定以 bash 執行此步驟。
    shell: bash

  # ---------------------------------------------------------------------------
  # Step 4：釋出並標註成品版本
  #   引用 akkuman/gitea-release-action，在 Gitea 上建立 release 並打 tag。
  #   依賴 Step 2 組好的 name / tag_name；若 Step 3 已 exit 1，本步驟不會執行。
  # ---------------------------------------------------------------------------
  - name: 釋出並標註成品版本
    # uses：引用第三方 akkuman/gitea-release-action，負責實際的 release 建立與 tag 標註。
    # 版本由 vars.ACTION_GITEA_RELEASE_VERSION 控制，集中管理被引用版本。
    uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
    # with：傳入 release action 所需的參數。
    with:
      # name：release 的顯示名稱，來自 Step 2 組出的 outputs.name（格式「<repo 名稱> v<版本>」）。
      name: ${{ steps.release-params.outputs.name }}
      # tag_name：release 對應的 tag 名稱，來自 Step 2 組出的 outputs.tag_name（格式「v<版本>」）。
      tag_name: ${{ steps.release-params.outputs.tag_name }}
      # target_commitish：release/tag 要指向的 ref（分支或 commit），這裡使用觸發此次執行的 gitea.ref。
      target_commitish: ${{ gitea.ref }}
      # files：要附加到 release 的成品檔案，來自本 action 的 inputs.files（呼叫方傳入，可為空）。
      files: ${{ inputs.files }}

  # ---------------------------------------------------------------------------
  # Step 5：清理舊成品
  #   引用 release-cleanup action，清理過舊的 release/成品，避免無限累積。
  # ---------------------------------------------------------------------------
  - name: 清理舊成品
    # uses：引用 Gitea 上 docker-actions/release-cleanup action 執行清理。
    # 版本由 vars.ACTION_RELEASE_CLEANUP_VERSION 控制。
    uses: https://gitea.jsc.idv.tw/docker-actions/release-cleanup@${{ vars.ACTION_RELEASE_CLEANUP_VERSION }}