298 lines
13 KiB
Markdown
298 lines
13 KiB
Markdown
# calculate-version
|
||
|
||
> 更新時間：2026/06/30 12:32:40
|
||
|
||
計算版本號的 Gitea Action。依現有 release 推算下一個穩定版或 beta 版本號，並將結果寫入 Action output `version`。核心邏輯以 Node.js 實作，置於 `app/`，由 `entrypoint.sh` 作為容器進入點啟動；容器映像採多階段建置（build 階段 `node:latest`、runtime 階段 `node:slim`）。
|
||
|
||
版本進位規則：`patch + 1`；當 `patch` 達 10 進位至 `minor`，`minor` 達 10 進位至 `major`。beta 版本號形如 `<next>-beta.<n>`，其中 `<n>` 為該版本既有 beta 標籤的最大序號加 1。
|
||
|
||
## 專案列表
|
||
|
||
### 專案描述
|
||
|
||
| 專案名稱 | 專案描述 |
|
||
| --- | --- |
|
||
| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 計算版本號的 Gitea Action：載入並驗證環境設定、分頁抓取 Gitea release、計算下一個穩定版或 beta 版本號，並寫出 Action output。 |
|
||
|
||
### 參考專案
|
||
|
||
| 專案名稱 | 參考專案列表 |
|
||
| --- | --- |
|
||
| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 無 |
|
||
|
||
### NuGet 套件
|
||
|
||
| 專案名稱 | NuGet 套件列表 |
|
||
| --- | --- |
|
||
| [calculate-version](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app) | 無（zero-dependency；僅使用 Node.js 內建模組與全域 fetch） |
|
||
|
||
## 功能列表
|
||
|
||
### index（app/index.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [index.main](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/index.js#L27) | [Action 進入點：協調設定載入、release 取得、版本計算與輸出（支援相依注入）。](#indexmain) |
|
||
|
||
### logger（app/logger.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [logger.section](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L45) | [輸出帶標題的區塊段落至標準輸出，標題前後以分隔線包夾。](#loggersection) |
|
||
| [logger.info](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L60) | [輸出 INF 層級 log 訊息，格式為 `[INF][時間]: 訊息`。](#loggerinfo) |
|
||
| [logger.error](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/logger.js#L77) | [輸出 ERR 層級訊息至 stderr（格式為 `[ERR][時間]: 訊息`，僅輸出不終止行程）。](#loggererror) |
|
||
|
||
### config（app/config.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [config.isUnset](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L11) | [判斷環境變數值是否視為「未設定」。](#configisunset) |
|
||
| [config.requireEnv](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L23) | [驗證必填環境變數，未設定時拋出錯誤。](#configrequireenv) |
|
||
| [config.normalizeBetaFlag](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L38) | [將 beta 旗標正規化為布林值。](#confignormalizebetaflag) |
|
||
| [config.loadConfig](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/config.js#L80) | [從環境變數載入並驗證執行所需的設定。](#configloadconfig) |
|
||
|
||
### version（app/version.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [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) | [取得 release 清單中最新的穩定版版本號字串。](#versionlateststableversion) |
|
||
| [version.nextReleaseVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L78) | [依最新穩定版計算下一個發行版本號。](#versionnextreleaseversion) |
|
||
| [version.nextBetaNumber](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L101) | [計算指定版本號的下一個 beta 流水號。](#versionnextbetanumber) |
|
||
| [version.calculateVersion](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/version.js#L126) | [計算最新穩定版與下一個版本號（支援 beta）。](#versioncalculateversion) |
|
||
|
||
### releases（app/releases.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [releases.fetchReleases](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/releases.js#L24) | [以分頁方式取得指定 Gitea repo 的所有 release。](#releasesfetchreleases) |
|
||
|
||
### output（app/output.js）
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [output.writeOutput](https://gitea.jsc.idv.tw/docker-actions/calculate-version/src/branch/develop/app/output.js#L16) | [將一行 `name=value` 附加寫入 Action 的輸出檔。](#outputwriteoutput) |
|
||
|
||
## 使用範例
|
||
|
||
<a id="indexmain"></a>
|
||
### index.main
|
||
|
||
Action 進入點：依序協調設定載入、release 取得、版本計算與輸出寫出，回傳計算出的版本號。失敗時向外拋出例外（由進入點頂層攔截並以狀態碼 1 結束）。相依模組可透過 `deps` 注入，便於測試。模組僅在被直接執行（`node app/index.js`）時自動啟動。
|
||
|
||
```js
|
||
const { main } = require('./index');
|
||
|
||
// 測試或自訂情境：注入假的相依
|
||
const version = await main({
|
||
loadConfig: () => ({ serverUrl: 'https://gitea.example.com', repository: 'owner/repo', token: null, isBeta: false }),
|
||
fetchReleases: async () => ([{ tag_name: 'v1.2.3' }]),
|
||
writeOutput: () => {},
|
||
log: { section() {}, info() {}, error() {} },
|
||
});
|
||
// version === '1.2.4'
|
||
```
|
||
|
||
<a id="loggersection"></a>
|
||
### logger.section
|
||
|
||
輸出帶標題的區塊段落至標準輸出：先一個換行，接著 50 個 `=` 的主分隔線、標題文字，最後 50 個 `-` 的次分隔線，用於在 log 中建立可視段落區隔。此為結構性段落標題，不套用 `[等級][時間]` 前綴。
|
||
|
||
```js
|
||
const logger = require('./logger');
|
||
|
||
logger.section('參數檢查');
|
||
// 輸出：
|
||
//
|
||
// ==================================================
|
||
// 參數檢查
|
||
// --------------------------------------------------
|
||
```
|
||
|
||
<a id="loggerinfo"></a>
|
||
### logger.info
|
||
|
||
輸出一般資訊（INF）層級訊息至標準輸出，格式統一為 `[INF][{時間}]: {訊息}`，時間使用台灣時區（Asia/Taipei）、格式 `yyyy/MM/dd HH:mm:ss`，並於結尾換行；不會結束行程。
|
||
|
||
```js
|
||
const logger = require('./logger');
|
||
|
||
logger.info('IS_BETA=false');
|
||
// 輸出：[INF][2026/06/30 12:00:00]: IS_BETA=false
|
||
```
|
||
|
||
<a id="loggererror"></a>
|
||
### logger.error
|
||
|
||
輸出錯誤（ERR）層級訊息至標準錯誤輸出（stderr），格式統一為 `[ERR][{時間}]: {訊息}`（時間為台灣時區）。僅負責輸出，**不終止行程**；是否結束由呼叫端（進入點）決定，以利測試與錯誤復原。
|
||
|
||
```js
|
||
const logger = require('./logger');
|
||
|
||
logger.error('GITEA_SERVER_URL 未設定');
|
||
// 對 stderr 輸出：[ERR][2026/06/30 12:00:00]: GITEA_SERVER_URL 未設定
|
||
```
|
||
|
||
<a id="configisunset"></a>
|
||
### config.isUnset
|
||
|
||
判斷環境變數值是否視為「未設定」。`undefined`、`null`、空字串、字面字串 `"null"` 皆視為未設定。
|
||
|
||
```js
|
||
const { isUnset } = require('./config');
|
||
|
||
isUnset(undefined); // true
|
||
isUnset('null'); // true
|
||
isUnset('false'); // false
|
||
```
|
||
|
||
<a id="configrequireenv"></a>
|
||
### config.requireEnv
|
||
|
||
驗證必填環境變數；未設定時拋出 `Error`（訊息為 `${name} 未設定`），已設定時原樣回傳值。
|
||
|
||
```js
|
||
const { requireEnv } = require('./config');
|
||
|
||
const url = requireEnv('GITEA_SERVER_URL', process.env.GITEA_SERVER_URL);
|
||
// 未設定時拋出：Error: GITEA_SERVER_URL 未設定
|
||
```
|
||
|
||
<a id="confignormalizebetaflag"></a>
|
||
### config.normalizeBetaFlag
|
||
|
||
將 beta 旗標正規化為布林值。未設定時預設為 `false`；僅當值嚴格等於字面字串 `"true"` 時回傳 `true`。
|
||
|
||
```js
|
||
const { normalizeBetaFlag } = require('./config');
|
||
|
||
normalizeBetaFlag('true'); // true
|
||
normalizeBetaFlag('TRUE'); // false（嚴格比較，不做大小寫轉換）
|
||
normalizeBetaFlag(undefined); // false
|
||
```
|
||
|
||
<a id="configloadconfig"></a>
|
||
### config.loadConfig
|
||
|
||
從環境變數載入並驗證執行所需的設定。`GITEA_SERVER_URL` 與 `GITEA_REPOSITORY` 為必填（未設定即拋錯），且 `GITEA_SERVER_URL` 須為合法的 http/https URL；`GITEA_TOKEN` 非必填（未設定為 `null`）；`IS_BETA` 會正規化為布林值。
|
||
|
||
```js
|
||
const { loadConfig } = require('./config');
|
||
|
||
const config = loadConfig({
|
||
GITEA_SERVER_URL: 'https://gitea.example.com',
|
||
GITEA_REPOSITORY: 'owner/repo',
|
||
IS_BETA: 'true',
|
||
});
|
||
// => { serverUrl: 'https://gitea.example.com', repository: 'owner/repo', token: null, isBeta: true }
|
||
```
|
||
|
||
<a id="versioncompareversionarrays"></a>
|
||
### version.compareVersionArrays
|
||
|
||
逐區段（element-wise）比較兩個版本號數值陣列，較短的陣列視為較小。回傳值 `> 0` 表示 a 大於 b、`< 0` 表示 a 小於 b、`0` 表示相等；相異區段回傳的是該段差值（非固定 ±1）。
|
||
|
||
```js
|
||
const { compareVersionArrays } = require('./version');
|
||
|
||
compareVersionArrays([1, 10], [1, 2, 3]); // > 0（1.10 > 1.2.3）
|
||
compareVersionArrays([1, 2], [1, 2, 0]); // < 0（較短者較小）
|
||
```
|
||
|
||
<a id="versionparsestableversions"></a>
|
||
### version.parseStableVersions
|
||
|
||
從 release 清單解析出所有穩定版（排除 beta、排除格式不合法者）的版本號數值陣列；會去除 tag 開頭的 `v`。傳入非陣列時回傳空陣列。
|
||
|
||
```js
|
||
const { parseStableVersions } = require('./version');
|
||
|
||
parseStableVersions([
|
||
{ tag_name: 'v1.2.3' },
|
||
{ tag_name: '2.0.0' },
|
||
{ tag_name: 'v1.0.0-beta.1' }, // 被排除
|
||
]);
|
||
// => [[1, 2, 3], [2, 0, 0]]
|
||
```
|
||
|
||
<a id="versionlateststableversion"></a>
|
||
### version.latestStableVersion
|
||
|
||
取得 release 清單中最新（最大）的穩定版版本號字串，固定格式化為三段 `major.minor.patch`；查無穩定版時回傳 `"0.0.0"`。
|
||
|
||
```js
|
||
const { latestStableVersion } = require('./version');
|
||
|
||
latestStableVersion([{ tag_name: 'v1.2.3' }, { tag_name: 'v1.9.9' }]); // "1.9.9"
|
||
latestStableVersion([]); // "0.0.0"
|
||
```
|
||
|
||
<a id="versionnextreleaseversion"></a>
|
||
### version.nextReleaseVersion
|
||
|
||
依最新穩定版字串計算下一個發行版本號：`patch + 1`，`patch` 達 10 進位至 `minor`，`minor` 達 10 進位至 `major`（「逢 10 進位」為本專案自訂約定，非標準 SemVer）。
|
||
|
||
```js
|
||
const { nextReleaseVersion } = require('./version');
|
||
|
||
nextReleaseVersion('1.2.8'); // "1.2.9"
|
||
nextReleaseVersion('1.2.9'); // "1.3.0"
|
||
nextReleaseVersion('1.9.9'); // "2.0.0"
|
||
```
|
||
|
||
<a id="versionnextbetanumber"></a>
|
||
### version.nextBetaNumber
|
||
|
||
計算指定版本號的下一個 beta 流水號：取現有相符 beta 標籤（`v<version>-beta.<n>`）的最大序號加 1，查無時回傳 `1`。`version` 參數不應含前綴 `v`。
|
||
|
||
```js
|
||
const { nextBetaNumber } = require('./version');
|
||
|
||
nextBetaNumber([{ tag_name: 'v1.3.0-beta.1' }, { tag_name: 'v1.3.0-beta.3' }], '1.3.0'); // 4
|
||
nextBetaNumber([], '1.3.0'); // 1
|
||
```
|
||
|
||
<a id="versioncalculateversion"></a>
|
||
### version.calculateVersion
|
||
|
||
計算最新穩定版與下一個版本號；`isBeta` 為 `true` 時產生 beta 版本號。回傳物件 `{ latest, version }`。
|
||
|
||
```js
|
||
const { calculateVersion } = require('./version');
|
||
|
||
calculateVersion([{ tag_name: 'v1.2.3' }], false);
|
||
// => { latest: '1.2.3', version: '1.2.4' }
|
||
|
||
calculateVersion([{ tag_name: 'v1.2.3' }], true);
|
||
// => { latest: '1.2.3', version: '1.2.4-beta.1' }
|
||
```
|
||
|
||
<a id="releasesfetchreleases"></a>
|
||
### releases.fetchReleases
|
||
|
||
以分頁方式取得指定 Gitea repo 的所有 release，並回傳合併後的陣列。使用全域 `fetch`（Node.js 18+）逐頁請求（每頁 limit 為 10）；當某頁回傳空資料、`null` 或筆數少於上限時即停止。提供 `options.token` 時以授權方式請求。網路失敗、回應讀取失敗、非 2xx、無法解析或非陣列回應時拋出 `Error`（含頁碼）。
|
||
|
||
```js
|
||
const { fetchReleases } = require('./releases');
|
||
const logger = require('./logger');
|
||
|
||
const releases = await fetchReleases(
|
||
'https://gitea.example.com/api/v1/repos/owner/repo/releases',
|
||
{ token: process.env.GITEA_TOKEN, logger },
|
||
);
|
||
// => 所有 release 物件合併後的陣列
|
||
```
|
||
|
||
<a id="outputwriteoutput"></a>
|
||
### output.writeOutput
|
||
|
||
將一行 `name=value` 附加寫入 GitHub/Gitea Action 的輸出檔（預設取 `process.env.GITHUB_OUTPUT`）。以 append 方式寫入、不覆蓋既有內容；輸出檔路徑為 falsy 時拋出 `Error`。
|
||
|
||
```js
|
||
const { writeOutput } = require('./output');
|
||
|
||
writeOutput('version', '1.2.4');
|
||
// 對 $GITHUB_OUTPUT 附加一行：version=1.2.4
|
||
```
|