docs(README 與文件草稿): 重整說明與草稿內容
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# calculate-version
|
||||
|
||||
更新時間：2026/07/11 14:03:52（Asia/Taipei）
|
||||
更新時間：2026/07/11 17:53:32（Asia/Taipei）
|
||||
|
||||
這個專案是一個 Gitea Docker action，會讀取 repository 的 release 清單，計算下一個正式版或 beta 版本號，並將結果輸出成 action output。
|
||||
|
||||
@@ -10,19 +10,19 @@
|
||||
|
||||
| 專案名稱 | 專案描述 |
|
||||
| --- | --- |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 這是一個用來計算 Gitea release 下一版版本號的 Node.js action，支援正式版與 beta 版推算。 |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 這是一個以 Node.js 實作的 Gitea Docker action，提供 release 擷取、版本解析、beta 推算與 action 主流程輸出。 |
|
||||
|
||||
### 參考專案表
|
||||
|
||||
| 專案名稱 | 參考專案列表 |
|
||||
| --- | --- |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 無 |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 無 |
|
||||
|
||||
### NuGet 套件表
|
||||
|
||||
| 專案名稱 | NuGet 套件列表 |
|
||||
| --- | --- |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 無 |
|
||||
| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 無 |
|
||||
|
||||
## 功能列表
|
||||
|
||||
@@ -30,8 +30,122 @@
|
||||
|
||||
| 功能名稱 | 功能描述 |
|
||||
| --- | --- |
|
||||
| 無 | 此專案未公開可列入 README 的功能。 |
|
||||
| [calculate-version.normalizeBetaFlag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L72) | [把空值或 `null` 正規化成 beta 旗標字串](#calculateversionnormalizebetaflag) |
|
||||
| [calculate-version.parseVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L107) | [把版本字串拆成數字片段](#calculateversionparseversionparts) |
|
||||
| [calculate-version.compareVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L125) | [逐段比較版本片段，供排序使用](#calculateversioncompareversionparts) |
|
||||
| [calculate-version.stableVersionFromTag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L148) | [解析穩定版 tag 為版本片段](#calculateversionstableversionfromtag) |
|
||||
| [calculate-version.latestStableVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L169) | [從 release 清單找出最新穩定版](#calculateversionlateststableversion) |
|
||||
| [calculate-version.nextReleaseVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L195) | [將正式版版本號遞增一版](#calculateversionnextreleaseversion) |
|
||||
| [calculate-version.nextBetaNumber](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L224) | [推算下一個 beta 編號](#calculateversionnextbetanumber) |
|
||||
| [calculate-version.calculateVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L252) | [回傳目前最新版本與下一個版本](#calculateversioncalculateversion) |
|
||||
| [calculate-version.fetchReleases](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L334) | [分頁抓取 repository release 清單](#calculateversionfetchreleases) |
|
||||
| [calculate-version.main](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L373) | [執行 action 主流程並輸出結果](#calculateversionmain) |
|
||||
|
||||
## 使用範例
|
||||
|
||||
此專案目前沒有可對外列入 README 的公開方法，因此沒有對應的使用範例。
|
||||
### <a id="calculateversionnormalizebetaflag"></a>calculate-version.normalizeBetaFlag
|
||||
把空值、`null` 或未定義值正規化成 `false`，讓後續版本判斷只處理字串。
|
||||
|
||||
```js
|
||||
const { normalizeBetaFlag } = require('./src/index.js');
|
||||
|
||||
const isBeta = normalizeBetaFlag(process.env.IS_BETA);
|
||||
```
|
||||
|
||||
### <a id="calculateversionparseversionparts"></a>calculate-version.parseVersionParts
|
||||
將版本字串拆成數字陣列，非數字片段會保守視為 `0`。
|
||||
|
||||
```js
|
||||
const { parseVersionParts } = require('./src/index.js');
|
||||
|
||||
const parts = parseVersionParts('1.2.3');
|
||||
```
|
||||
|
||||
### <a id="calculateversioncompareversionparts"></a>calculate-version.compareVersionParts
|
||||
逐段比較兩組版本片段，適合搭配 `Array.prototype.sort()` 使用。
|
||||
|
||||
```js
|
||||
const { compareVersionParts } = require('./src/index.js');
|
||||
|
||||
const sorted = [[1, 2, 10], [1, 2, 3]].sort(compareVersionParts);
|
||||
```
|
||||
|
||||
### <a id="calculateversionstableversionfromtag"></a>calculate-version.stableVersionFromTag
|
||||
從 tag 名稱擷取穩定版版本資訊，像 `v1.2.3` 會被解析成版本片段。
|
||||
|
||||
```js
|
||||
const { stableVersionFromTag } = require('./src/index.js');
|
||||
|
||||
const parts = stableVersionFromTag('v1.2.3');
|
||||
```
|
||||
|
||||
### <a id="calculateversionlateststableversion"></a>calculate-version.latestStableVersion
|
||||
從 release 清單中找出最新的穩定版版本號，找不到時回傳 `0.0.0`。
|
||||
|
||||
```js
|
||||
const { latestStableVersion } = require('./src/index.js');
|
||||
|
||||
const latest = latestStableVersion([
|
||||
{ tag_name: 'v1.2.2' },
|
||||
{ tag_name: 'v1.2.3-beta.1' },
|
||||
{ tag_name: 'v1.2.3' },
|
||||
]);
|
||||
```
|
||||
|
||||
### <a id="calculateversionnextreleaseversion"></a>calculate-version.nextReleaseVersion
|
||||
將正式版版本號遞增一版，`patch` 與 `minor` 都會以 10 為進位界線。
|
||||
|
||||
```js
|
||||
const { nextReleaseVersion } = require('./src/index.js');
|
||||
|
||||
const nextVersion = nextReleaseVersion('1.2.9');
|
||||
```
|
||||
|
||||
### <a id="calculateversionnextbetanumber"></a>calculate-version.nextBetaNumber
|
||||
推算下一個 beta 編號，會找出目前版本對應的最大 `beta.N` 再加一。
|
||||
|
||||
```js
|
||||
const { nextBetaNumber } = require('./src/index.js');
|
||||
|
||||
const betaNumber = nextBetaNumber([
|
||||
{ tag_name: 'v1.2.4-beta.1' },
|
||||
{ tag_name: 'v1.2.4-beta.3' },
|
||||
], '1.2.4');
|
||||
```
|
||||
|
||||
### <a id="calculateversioncalculateversion"></a>calculate-version.calculateVersion
|
||||
回傳目前最新版本與下一個版本，beta 模式時會產生對應的 `-beta.N` 結果。
|
||||
|
||||
```js
|
||||
const { calculateVersion } = require('./src/index.js');
|
||||
|
||||
const [latest, nextVersion] = calculateVersion([
|
||||
{ tag_name: 'v1.2.3' },
|
||||
{ tag_name: 'v1.2.4-beta.1' },
|
||||
], 'false');
|
||||
```
|
||||
|
||||
### <a id="calculateversionfetchreleases"></a>calculate-version.fetchReleases
|
||||
分頁抓取 repository 的 release 清單，直到 API 回傳空資料或最後一頁不足頁面上限。
|
||||
|
||||
```js
|
||||
const { fetchReleases } = require('./src/index.js');
|
||||
|
||||
// 需人工確認：baseUrl 與 repository 必須對應實際 Gitea 環境。
|
||||
(async () => {
|
||||
const releases = await fetchReleases('https://gitea.example.com', 'owner/repo', 'token-value');
|
||||
console.log(releases);
|
||||
})();
|
||||
```
|
||||
|
||||
### <a id="calculateversionmain"></a>calculate-version.main
|
||||
執行 action 主流程，會讀取環境變數、抓取 release、計算版本並輸出結果。
|
||||
|
||||
```js
|
||||
const { main } = require('./src/index.js');
|
||||
|
||||
// 需人工確認：這個入口通常應由 Gitea action 啟動，且需要完整環境變數。
|
||||
(async () => {
|
||||
await main();
|
||||
})();
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user