docs(指令檔與 README): 補齊 action.yml 與 CI/CD workflow 逐行註解並重建 README

README.md

@@ -1,6 +1,8 @@
 # Release Tag Version
 
-更新時間：2026/06/26 00:48:28
+更新時間：2026/06/26 10:47:20
+
+本專案為 Gitea Actions 的 **composite action**，用來自動計算版本號、建立 release 並標註對應 tag，最後清理舊成品。
 
 ## 專案列表
 
@@ -8,7 +10,7 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [Release Tag Version](https://gitea.jsc.idv.tw/composite-actions/release-tag-version/src/branch/develop) | Gitea composite action，負責計算版本號、建立 release tag，並清理舊成品。此專案未公開可列入 README 的程式方法。 |
+| [Release Tag Version](https://gitea.jsc.idv.tw/composite-actions/release-tag-version/src/branch/develop) | Gitea composite action，依序呼叫 calculate-version 計算版本號、組合 release 參數、以 akkuman/gitea-release-action 建立 release 與 tag，再以 release-cleanup 清理舊成品。此專案未公開可列入 README 的程式方法。 |
 
 ### 參考專案
 
@@ -24,18 +26,56 @@
 
 ## 功能列表
 
-目前未偵測到可列入 README 的 public method、public constructor、public extension method 或 public operator。
+本專案為 YAML 定義的 Gitea composite action 與 workflow，未包含任何可文件化的 public method、public constructor、public extension method 或 public operator，因此沒有可列入的功能項目。
 
 ## 使用範例
 
-此專案提供 Gitea composite action，可在 workflow 中引用：
+本專案不提供程式方法，而是提供一個可被其他 workflow 引用的 Gitea composite action。
+
+### 在其他 repo 的 workflow 中引用
 
 ```yaml
 steps:
+- name: 取得程式碼
+  uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
 - name: 釋出並標註成品版本
-  uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@v0.0.4
+  uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@<version>
   with:
+    # files 為非必填；指定要隨 release 一起釋出（上傳）的成品檔案，可省略。
     files: dist/*
 ```
 
-執行時會先計算版本號，再建立對應 release/tag，最後清理舊成品。需確認相關 action 版本變數與權限已在 Gitea workflow 環境中設定。
+### 本 repo 內的 CD workflow（`.gitea/workflows/cd.yaml`）
+
+```yaml
+on:
+  push:
+    branches:
+    - master
+jobs:
+  release-tag-version:
+    name: Release Tag Version
+    runs-on: ubuntu
+    steps:
+    - name: 取得程式碼
+      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+    - name: 釋出並標註成品版本
+      # uses: ./ 引用本 repo 根目錄的 composite action（action.yml）
+      uses: ./
+```
+
+### 執行流程與前置條件
+
+引用後，composite action 會依序執行：
+
+1. **版本號計算**：呼叫 `docker-actions/calculate-version` 算出本次版本號。
+2. **組合釋出參數**：版本號非空時，組出 release 的 `name`（格式 `<repo 名稱> v<版本>`）與 `tag_name`（格式 `v<版本>`）。
+3. **檢查版本號輸出**：版本號為空時輸出錯誤訊息並 `exit 1`，中止流程，避免建立錯誤的 release/tag。
+4. **釋出並標註成品版本**：以 `akkuman/gitea-release-action` 建立 release 並打 tag，附帶 `files` 指定的成品。
+5. **清理舊成品**：呼叫 `docker-actions/release-cleanup` 清理過舊的 release。
+
+**前置條件**（需於 Gitea repo/organization 環境設定）：
+
+- 變數 `vars.ACTION_CALCULATE_VERSION`、`vars.ACTION_GITEA_RELEASE_VERSION`、`vars.ACTION_RELEASE_CLEANUP_VERSION`、`vars.ACTION_CHECKOUT_VERSION` 皆需設定且值有效。
+- runner 需有 `ubuntu` label。
+- 預期結果：在 Gitea 上建立 `v<版本>` 的 release 與 tag，並清理舊成品。