docs(calculate-version): 重建 README、修正 compareVersionArrays JSDoc 並更新指令檔註解日期
This commit is contained in:
Jeffery
@@ -1,7 +1,7 @@
|
||||
# =============================================================================
|
||||
# 用途: calculate-version 專案的 CD workflow。
|
||||
# 在程式碼推送至 master 分支時,自動釋出並標註 (tag) 成品版本。
|
||||
# 更新日期: 2026/06/30 12:13:04
|
||||
# 更新日期: 2026/06/30 17:18:23
|
||||
# =============================================================================
|
||||
|
||||
# workflow 名稱,顯示於 Gitea Actions 介面。
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
# 在 Pull Request 開啟或更新 (且目標分支非 master) 時,先以 composite
|
||||
# action 釋出並標註 beta 成品版本,再用剛標註出的版本呼叫
|
||||
# calculate-version action 計算版本號。
|
||||
# 更新日期: 2026/06/30 16:31:09
|
||||
# 更新日期: 2026/06/30 17:18:23
|
||||
# =============================================================================
|
||||
|
||||
# workflow 名稱,顯示於 Gitea Actions 介面。
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
# 用途: 建置 calculate-version Action 的容器映像。
|
||||
# 採多階段建置：build 階段以最新 node 準備主程式 (/app) 與進入點腳本，
|
||||
# runtime 階段改用 node slim 基底縮小最終映像，再由 entrypoint.sh 啟動 Node.js 主程式。
|
||||
# 更新日期: 2026/06/30 12:12:52
|
||||
# 更新日期: 2026/06/30 17:18:23
|
||||
# =============================================================================
|
||||
|
||||
# 1. 參數處理：node 版本以 ARG 注入。預設使用最新版 (build: node:latest / runtime: node:slim)；
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
計算版本號的 Gitea Action：依儲存庫現有的 release，推算下一個穩定版或 beta 版本號，並寫出為 Action output 供後續步驟取用。以 Docker 容器執行，容器內由 Node.js 主程式實作。
|
||||
|
||||
> 更新時間：2026/06/30 16:42:27（Asia/Taipei）
|
||||
> 更新時間：2026/06/30 17:38:51（Asia/Taipei）
|
||||
|
||||
## 專案列表
|
||||
|
||||
@@ -40,13 +40,13 @@
|
||||
| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77) | [輸出 `[ERR][時間]` 格式的錯誤訊息至標準錯誤輸出。](#loggererror) |
|
||||
| [output.writeOutput](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/output.js#L16) | [將一行 `name=value` 附加寫入 Action 的輸出檔。](#outputwriteoutput) |
|
||||
| [releases.fetchReleases](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/releases.js#L24) | [以分頁方式取得指定 Gitea repo 的所有 release。](#releasesfetchreleases) |
|
||||
| [version.compareVersionArrays](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L14) | [逐區段比較兩個版本號數值陣列，較短者視為較小。](#versioncompareversionarrays) |
|
||||
| [version.parseStableVersions](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L38) | [從 release 清單解析出所有穩定版的版本號數值陣列。](#versionparsestableversions) |
|
||||
| [version.latestStableVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L57) | [取得最新（最大）的穩定版版本號字串。](#versionlateststableversion) |
|
||||
| [version.nextReleaseVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L78) | [依最新穩定版計算下一個發行版本號（逢 10 進位）。](#versionnextreleaseversion) |
|
||||
| [version.nextBetaNumber](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L101) | [計算指定版本號的下一個 beta 流水號。](#versionnextbetanumber) |
|
||||
| [version.nextVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L130) | [依已知的最新穩定版計算本次要使用的版本號（含 beta）。](#versionnextversion) |
|
||||
| [version.calculateVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L146) | [計算最新穩定版與下一個版本號。](#versioncalculateversion) |
|
||||
| [version.compareVersionArrays](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L15) | [逐區段比較兩個版本號數值陣列，較短者視為較小。](#versioncompareversionarrays) |
|
||||
| [version.parseStableVersions](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L39) | [從 release 清單解析出所有穩定版的版本號數值陣列。](#versionparsestableversions) |
|
||||
| [version.latestStableVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L58) | [取得最新（最大）的穩定版版本號字串。](#versionlateststableversion) |
|
||||
| [version.nextReleaseVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L79) | [依最新穩定版計算下一個發行版本號（逢 10 進位）。](#versionnextreleaseversion) |
|
||||
| [version.nextBetaNumber](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L102) | [計算指定版本號的下一個 beta 流水號。](#versionnextbetanumber) |
|
||||
| [version.nextVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L131) | [依已知的最新穩定版計算本次要使用的版本號（含 beta）。](#versionnextversion) |
|
||||
| [version.calculateVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L147) | [計算最新穩定版與下一個版本號。](#versioncalculateversion) |
|
||||
|
||||
## 使用範例
|
||||
|
||||
@@ -142,7 +142,7 @@ logger.section('參數檢查');
|
||||
const logger = require('./app/logger');
|
||||
|
||||
logger.info('NEW_VERSION=1.2.4');
|
||||
// 輸出：[INF][2026/06/30 16:42:27]: NEW_VERSION=1.2.4
|
||||
// 輸出：[INF][2026/06/30 17:38:51]: NEW_VERSION=1.2.4
|
||||
```
|
||||
|
||||
<a id="loggererror"></a>
|
||||
@@ -154,7 +154,7 @@ logger.info('NEW_VERSION=1.2.4');
|
||||
const logger = require('./app/logger');
|
||||
|
||||
logger.error('GITEA_SERVER_URL 未設定');
|
||||
// stderr 輸出：[ERR][2026/06/30 16:42:27]: GITEA_SERVER_URL 未設定
|
||||
// stderr 輸出：[ERR][2026/06/30 17:38:51]: GITEA_SERVER_URL 未設定
|
||||
```
|
||||
|
||||
<a id="outputwriteoutput"></a>
|
||||
@@ -187,7 +187,7 @@ const releases = await fetchReleases(
|
||||
<a id="versioncompareversionarrays"></a>
|
||||
### version.compareVersionArrays
|
||||
|
||||
逐區段（element-wise）比較兩個版本號數值陣列，較短的陣列視為較小。回傳大於 0 表示 `a` 大於 `b`、小於 0 表示 `a` 小於 `b`、0 表示相等。
|
||||
逐區段（element-wise）比較兩個版本號數值陣列，較短的陣列視為較小。回傳大於 0 表示 `a` 大於 `b`、小於 0 表示 `a` 小於 `b`、0 表示相等；相異區段回傳的是該段差值（非固定 ±1）。傳入 `null`／`undefined` 會在讀取 `.length` 時拋 `TypeError`。
|
||||
|
||||
```js
|
||||
const { compareVersionArrays } = require('./app/version');
|
||||
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
# =============================================================================
|
||||
# 用途：此檔為 calculate-version Gitea Action 的定義，宣告其 inputs（is_beta）、
|
||||
# outputs（version）與以 docker 方式執行時注入給容器的環境變數。
|
||||
# 更新日期：2026/06/30 16:31:09
|
||||
# 更新日期：2026/06/30 17:18:23
|
||||
# =============================================================================
|
||||
|
||||
# Action 名稱，會顯示於 Gitea workflow 執行畫面上以利辨識
|
||||
|
||||
+2
-1
@@ -9,7 +9,8 @@ const SEGMENT_LIMIT = 10;
|
||||
* @param {number[]} b - 第二個版本號區段陣列，例如 [1, 2, 0]。
|
||||
* @returns {number} 大於 0 表示 a 大於 b；小於 0 表示 a 小於 b；0 表示兩者相等。
|
||||
* 相異區段回傳的是該段差值（非固定 ±1）。
|
||||
* @throws {TypeError} 當 a 或 b 非陣列（無 length 屬性）時拋出。
|
||||
* @throws {TypeError} 當 a 或 b 為 null/undefined（讀取 .length 即報錯）時拋出；
|
||||
* 傳入「有 length 但非數值陣列」（如字串）不會拋例外，但會得到非預期結果。
|
||||
*/
|
||||
function compareVersionArrays(a, b) {
|
||||
const length = Math.max(a.length, b.length);
|
||||
|
||||
+2
-2
@@ -3,7 +3,7 @@
|
||||
# 用途: calculate-version Action 的容器進入點 (entrypoint)。
|
||||
# 專案已由 bash 改寫為 Node.js,本腳本先輸出 Action 資訊橫幅,
|
||||
# 再啟動 /app/index.js,並將容器收到的引數原封傳遞給 Node.js 程式。
|
||||
# 更新日期: 2026/06/30 12:12:56
|
||||
# 更新日期: 2026/06/30 17:18:23
|
||||
# =============================================================================
|
||||
|
||||
# set -e: 任一指令失敗即中止; set -u: 使用未定義變數即報錯;
|
||||
@@ -13,7 +13,7 @@ set -euo pipefail
|
||||
# Action 基本資訊：與 action.yaml 的 name/description 一致；更新時間為本腳本最後異動的台灣時間。
|
||||
ACTION_NAME='Calculate Version'
|
||||
ACTION_DESC='計算版本號'
|
||||
ACTION_UPDATED='2026/06/30 12:12:56'
|
||||
ACTION_UPDATED='2026/06/30 17:18:23'
|
||||
|
||||
# 啟動時印出 Action 名稱 / 用途 / 更新時間橫幅,方便在 CI/容器 log 中辨識本次執行。
|
||||
printf '\n%s\n' '=================================================='
|
||||
|
||||
Reference in New Issue
Block a user