old-docker-actions/calculate-version
2
0
Fork 0
Code Pull Requests Actions Releases 4 Activity

docs(calculate-version): 重建 README 並補齊指令檔註解與 logger JSDoc #12

Merged
admin merged 6 commits from develop into master 2026-06-30 10:24:19 +00:00
Conversation 1 Commits 6 Files Changed 11
+19 -18
7 changed files with 19 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 7de0900d5f - Show all commits
.gitea/workflows/cd.yaml
+1 -1
View File
@@ -1,7 +1,7 @@
# ============================================================================= # =============================================================================
# 用途: calculate-version 專案的 CD workflow。 # 用途: calculate-version 專案的 CD workflow。
# 在程式碼推送至 master 分支時,自動釋出並標註 (tag) 成品版本。 # 在程式碼推送至 master 分支時,自動釋出並標註 (tag) 成品版本。
# 更新日期: 2026/06/30 12:13:04 # 更新日期: 2026/06/30 17:18:23
# ============================================================================= # =============================================================================
# workflow 名稱,顯示於 Gitea Actions 介面。 # workflow 名稱,顯示於 Gitea Actions 介面。
.gitea/workflows/ci.yaml
+1 -1
View File
@@ -3,7 +3,7 @@
# 在 Pull Request 開啟或更新 (且目標分支非 master) 時,先以 composite # 在 Pull Request 開啟或更新 (且目標分支非 master) 時,先以 composite
# action 釋出並標註 beta 成品版本,再用剛標註出的版本呼叫 # action 釋出並標註 beta 成品版本,再用剛標註出的版本呼叫
# calculate-version action 計算版本號。 # calculate-version action 計算版本號。
# 更新日期: 2026/06/30 16:31:09 # 更新日期: 2026/06/30 17:18:23
# ============================================================================= # =============================================================================
# workflow 名稱,顯示於 Gitea Actions 介面。 # workflow 名稱,顯示於 Gitea Actions 介面。
Dockerfile
+1 -1
View File
@@ -3,7 +3,7 @@
# 用途: 建置 calculate-version Action 的容器映像。 # 用途: 建置 calculate-version Action 的容器映像。
# 採多階段建置：build 階段以最新 node 準備主程式 (/app) 與進入點腳本， # 採多階段建置：build 階段以最新 node 準備主程式 (/app) 與進入點腳本，
# runtime 階段改用 node slim 基底縮小最終映像，再由 entrypoint.sh 啟動 Node.js 主程式。 # 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)； # 1. 參數處理：node 版本以 ARG 注入。預設使用最新版 (build: node:latest / runtime: node:slim)；
README.md
+11 -11
View File
@@ -2,7 +2,7 @@
計算版本號的 Gitea Action：依儲存庫現有的 release，推算下一個穩定版或 beta 版本號，並寫出為 Action output 供後續步驟取用。以 Docker 容器執行，容器內由 Node.js 主程式實作。 計算版本號的 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) | | [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) | | [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) | | [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.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#L38) | [從 release 清單解析出所有穩定版的版本號數值陣列。](#versionparsestableversions) | | [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#L57) | [取得最新（最大）的穩定版版本號字串。](#versionlateststableversion) | | [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#L78) | [依最新穩定版計算下一個發行版本號（逢 10 進位）。](#versionnextreleaseversion) | | [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#L101) | [計算指定版本號的下一個 beta 流水號。](#versionnextbetanumber) | | [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#L130) | [依已知的最新穩定版計算本次要使用的版本號（含 beta）。](#versionnextversion) | | [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#L146) | [計算最新穩定版與下一個版本號。](#versioncalculateversion) | | [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'); const logger = require('./app/logger');
logger.info('NEW_VERSION=1.2.4'); 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> <a id="loggererror"></a>
@@ -154,7 +154,7 @@ logger.info('NEW_VERSION=1.2.4');
const logger = require('./app/logger'); const logger = require('./app/logger');
logger.error('GITEA_SERVER_URL 未設定'); 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> <a id="outputwriteoutput"></a>
@@ -187,7 +187,7 @@ const releases = await fetchReleases(
<a id="versioncompareversionarrays"></a> <a id="versioncompareversionarrays"></a>
### version.compareVersionArrays ### 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 ```js
const { compareVersionArrays } = require('./app/version'); const { compareVersionArrays } = require('./app/version');
action.yaml
+1 -1
View File
@@ -1,7 +1,7 @@
# ============================================================================= # =============================================================================
# 用途：此檔為 calculate-version Gitea Action 的定義，宣告其 inputs（is_beta）、 # 用途：此檔為 calculate-version Gitea Action 的定義，宣告其 inputs（is_beta）、
# outputs（version）與以 docker 方式執行時注入給容器的環境變數。 # outputs（version）與以 docker 方式執行時注入給容器的環境變數。
# 更新日期：2026/06/30 16:31:09 # 更新日期：2026/06/30 17:18:23
# ============================================================================= # =============================================================================
# Action 名稱，會顯示於 Gitea workflow 執行畫面上以利辨識 # Action 名稱，會顯示於 Gitea workflow 執行畫面上以利辨識
app/version.js
+2 -1
View File
@@ -9,7 +9,8 @@ const SEGMENT_LIMIT = 10;
* @param {number[]} b - 第二個版本號區段陣列，例如 [1, 2, 0]。 * @param {number[]} b - 第二個版本號區段陣列，例如 [1, 2, 0]。
* @returns {number} 大於 0 表示 a 大於 b；小於 0 表示 a 小於 b；0 表示兩者相等。 * @returns {number} 大於 0 表示 a 大於 b；小於 0 表示 a 小於 b；0 表示兩者相等。
* 相異區段回傳的是該段差值（非固定 ±1）。 * 相異區段回傳的是該段差值（非固定 ±1）。
* @throws {TypeError} 當 a 或 b 非陣列（無 length 屬性）時拋出。 * @throws {TypeError} 當 a 或 b 為 null/undefined（讀取 .length 即報錯）時拋出；
* 傳入「有 length 但非數值陣列」（如字串）不會拋例外，但會得到非預期結果。
*/ */
function compareVersionArrays(a, b) { function compareVersionArrays(a, b) {
const length = Math.max(a.length, b.length); const length = Math.max(a.length, b.length);
entrypoint.sh
+2 -2
View File
@@ -3,7 +3,7 @@
# 用途: calculate-version Action 的容器進入點 (entrypoint)。 # 用途: calculate-version Action 的容器進入點 (entrypoint)。
# 專案已由 bash 改寫為 Node.js,本腳本先輸出 Action 資訊橫幅, # 專案已由 bash 改寫為 Node.js,本腳本先輸出 Action 資訊橫幅,
# 再啟動 /app/index.js,並將容器收到的引數原封傳遞給 Node.js 程式。 # 再啟動 /app/index.js,並將容器收到的引數原封傳遞給 Node.js 程式。
# 更新日期: 2026/06/30 12:12:56 # 更新日期: 2026/06/30 17:18:23
# ============================================================================= # =============================================================================
# set -e: 任一指令失敗即中止; set -u: 使用未定義變數即報錯; # set -e: 任一指令失敗即中止; set -u: 使用未定義變數即報錯;
@@ -13,7 +13,7 @@ set -euo pipefail
# Action 基本資訊：與 action.yaml 的 name/description 一致；更新時間為本腳本最後異動的台灣時間。 # Action 基本資訊：與 action.yaml 的 name/description 一致；更新時間為本腳本最後異動的台灣時間。
ACTION_NAME='Calculate Version' ACTION_NAME='Calculate Version'
ACTION_DESC='計算版本號' ACTION_DESC='計算版本號'
ACTION_UPDATED='2026/06/30 12:12:56' ACTION_UPDATED='2026/06/30 17:18:23'
# 啟動時印出 Action 名稱 / 用途 / 更新時間橫幅,方便在 CI/容器 log 中辨識本次執行。 # 啟動時印出 Action 名稱 / 用途 / 更新時間橫幅,方便在 CI/容器 log 中辨識本次執行。
printf '\n%s\n' '==================================================' printf '\n%s\n' '=================================================='