docs(release-cleanup): 補齊 CI workflow 註解、統一日誌格式並重建 README
- .gitea/workflows/ci.yaml、cd.yaml：新增用途/更新日期區塊與逐行註解（指令邏輯不變） - app/index.js：日誌統一為 [等級][台灣時間]: 訊息（新增 timestamp helper，INF/WRN/ERR；行為、控制流、exit code、stdout/stderr 皆等價） - README.md：重建專案列表三表/功能列表/使用範例，新增日誌格式說明與 timestamp 功能 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeffery
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
cee5b2f67f
commit
15381d07a7
@@ -1,6 +1,6 @@
|
||||
# Release Cleanup
|
||||
|
||||
> 更新時間：2026/06/30 12:02:55（台灣時區 Asia/Taipei）
|
||||
> 更新時間：2026/06/30 17:58:12（台灣時區 Asia/Taipei）
|
||||
|
||||
清理舊成品的 **Gitea / GitHub docker container action**。依保留數量清理 repo 的舊 release，並刪除沒有對應 release 的 tag；正式版與 beta 版各自獨立保留指定數量。
|
||||
|
||||
@@ -16,6 +16,18 @@
|
||||
|
||||
`GITEA_TOKEN` 為空時以匿名身分呼叫 API。取得分頁失敗或參數不合法則直接以 exit code 1 結束程序。
|
||||
|
||||
## 日誌輸出格式
|
||||
|
||||
所有等級式輸出統一為 `[{等級}][{時間}]: {訊息}`（等級為 `INF`/`WRN`/`ERR`，時間為 Asia/Taipei 的 `yyyy/MM/dd HH:mm:ss`）；`fail` 走 stderr，其餘走 stdout。例如：
|
||||
|
||||
```text
|
||||
[INF][2026/06/30 17:58:12]: RELEASE_COUNT=42
|
||||
[WRN][2026/06/30 17:58:12]: GITEA_TOKEN is empty; release API calls will be anonymous
|
||||
[ERR][2026/06/30 17:58:12]: 刪除失敗: v1.0.0 (Release 1.0.0), HTTP 500
|
||||
```
|
||||
|
||||
> 註：`separator` / `section` 為純分隔線／標題輸出，不帶等級與時間戳。
|
||||
|
||||
## Action 輸入與環境變數
|
||||
|
||||
| 名稱 | 來源 | 必填 | 預設 | 說明 |
|
||||
@@ -44,7 +56,7 @@ jobs:
|
||||
|
||||
| 專案名稱 | 專案描述 |
|
||||
| --- | --- |
|
||||
| [release-cleanup](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app) | 清理 Gitea repo 舊 release 與孤兒 tag 的 docker container action；正式版與 beta 版各自保留指定數量 |
|
||||
| [release-cleanup](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app) | 清理 Gitea repo 舊 release 與孤兒 tag 的 docker container action；正式版與 beta 版各自保留指定數量，並以統一等級式日誌輸出處理過程 |
|
||||
|
||||
### 參考專案
|
||||
|
||||
@@ -64,19 +76,22 @@ jobs:
|
||||
|
||||
### release-cleanup
|
||||
|
||||
> 說明：本專案為單一 Node 模組（`app/index.js`），下列為模組內可文件化的頂層函式（不含 `main` 內部的巢狀私有函式 `fetchAllPages` / `deleteUrl`）。
|
||||
|
||||
| 功能名稱 | 功能描述 |
|
||||
| --- | --- |
|
||||
| [separator](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L10) | [在 stdout 輸出視覺分隔線](#separator) |
|
||||
| [section](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L21) | [輸出區段標題區塊](#section) |
|
||||
| [info](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L33) | [以 \[INFO\] 前綴輸出資訊訊息](#info) |
|
||||
| [success](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L43) | [以 \[OK\] 前綴輸出成功訊息](#success) |
|
||||
| [warn](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L53) | [以 \[WARN\] 前綴輸出警告訊息](#warn) |
|
||||
| [fail](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L64) | [以 \[ERR\] 前綴輸出錯誤訊息到 stderr](#fail) |
|
||||
| [isEmptyOrNull](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L76) | [判斷值是否視為空 / 未設定](#isemptyornull) |
|
||||
| [requireValue](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L89) | [檢查必填值，空值時結束程序](#requirevalue) |
|
||||
| [requireInteger](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L106) | [驗證非負整數，不符時結束程序](#requireinteger) |
|
||||
| [isBeta](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L120) | [判斷名稱是否為 beta 版本](#isbeta) |
|
||||
| [main](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L140) | [Action 主流程：清理舊 release 與孤兒 tag](#main) |
|
||||
| [timestamp](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L34) | [取得 Asia/Taipei 時間字串](#timestamp) |
|
||||
| [info](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L46) | [以 \[INF\] 等級輸出資訊訊息](#info) |
|
||||
| [success](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L57) | [以 \[INF\] 等級輸出成功訊息](#success) |
|
||||
| [warn](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L67) | [以 \[WRN\] 等級輸出警告訊息](#warn) |
|
||||
| [fail](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L78) | [以 \[ERR\] 等級輸出錯誤訊息到 stderr](#fail) |
|
||||
| [isEmptyOrNull](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L90) | [判斷值是否視為空 / 未設定](#isemptyornull) |
|
||||
| [requireValue](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L103) | [檢查必填值，空值時結束程序](#requirevalue) |
|
||||
| [requireInteger](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L120) | [驗證非負整數，不符時結束程序](#requireinteger) |
|
||||
| [isBeta](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L134) | [判斷名稱是否為 beta 版本](#isbeta) |
|
||||
| [main](https://gitea.jsc.idv.tw/docker-actions/release-cleanup/src/branch/develop/app/index.js#L154) | [Action 主流程：清理舊 release 與孤兒 tag](#main) |
|
||||
|
||||
## 使用範例
|
||||
|
||||
@@ -105,43 +120,58 @@ section('參數檢查');
|
||||
// --------------------------------------------------
|
||||
```
|
||||
|
||||
<a id="timestamp"></a>
|
||||
### timestamp
|
||||
|
||||
取得目前 **Asia/Taipei** 時區的時間字串，格式為 `yyyy/MM/dd HH:mm:ss`。使用 Node 內建 `Intl`（`toLocaleString('sv-SE')` 輸出 24 小時制再把 `-` 換成 `/`），不需額外相依。供各等級式 log helper 組裝統一格式前綴使用。
|
||||
|
||||
```js
|
||||
timestamp();
|
||||
// 例如回傳： '2026/06/30 17:58:12'
|
||||
info(`RELEASE_COUNT=42`);
|
||||
// 內部即以 timestamp() 組出： [INF][2026/06/30 17:58:12]: RELEASE_COUNT=42
|
||||
```
|
||||
|
||||
> 前置條件：執行環境須支援 `Intl`（Node 18+ 內建）。結果：回傳當下台灣時間字串，無副作用。
|
||||
|
||||
<a id="info"></a>
|
||||
### info
|
||||
|
||||
以 `[INFO]` 前綴將一般資訊訊息輸出到 stdout（`console.log`）。
|
||||
以 `[INF][時間]:` 前綴將一般資訊訊息輸出到 stdout（`console.log`，時間為 Asia/Taipei）。
|
||||
|
||||
```js
|
||||
info('RELEASE_COUNT=10');
|
||||
// 輸出：[INFO] RELEASE_COUNT=10
|
||||
// 輸出：[INF][2026/06/30 17:58:12]: RELEASE_COUNT=10
|
||||
```
|
||||
|
||||
<a id="success"></a>
|
||||
### success
|
||||
|
||||
以 `[OK]` 前綴將成功訊息輸出到 stdout。
|
||||
以 `[INF][時間]:` 前綴將成功訊息輸出到 stdout。規範等級碼無「成功」一項，故等級採 `INF`，成功語意保留於訊息文字。
|
||||
|
||||
```js
|
||||
success('成功刪除: v1.0.0 (Release 1.0.0)');
|
||||
// 輸出：[OK] 成功刪除: v1.0.0 (Release 1.0.0)
|
||||
// 輸出：[INF][2026/06/30 17:58:12]: 成功刪除: v1.0.0 (Release 1.0.0)
|
||||
```
|
||||
|
||||
<a id="warn"></a>
|
||||
### warn
|
||||
|
||||
以 `[WARN]` 前綴將警告訊息輸出到 stdout（非致命情況，程式會繼續執行）。
|
||||
以 `[WRN][時間]:` 前綴將警告訊息輸出到 stdout（非致命情況，程式會繼續執行）。
|
||||
|
||||
```js
|
||||
warn('GITEA_TOKEN is empty; release API calls will be anonymous');
|
||||
// 輸出：[WARN] GITEA_TOKEN is empty; release API calls will be anonymous
|
||||
// 輸出：[WRN][2026/06/30 17:58:12]: GITEA_TOKEN is empty; release API calls will be anonymous
|
||||
```
|
||||
|
||||
<a id="fail"></a>
|
||||
### fail
|
||||
|
||||
以 `[ERR]` 前綴將錯誤訊息輸出到 **stderr**（`console.error`）。僅負責輸出，不會結束程序；是否離開由呼叫端決定。
|
||||
以 `[ERR][時間]:` 前綴將錯誤訊息輸出到 **stderr**（`console.error`）。僅負責輸出，不會結束程序；是否離開由呼叫端決定。
|
||||
|
||||
```js
|
||||
fail('刪除失敗: v0.1.0 (Release 0.1.0), HTTP 500');
|
||||
// 輸出（stderr）：[ERR][2026/06/30 17:58:12]: 刪除失敗: v0.1.0 (Release 0.1.0), HTTP 500
|
||||
process.exit(1); // 終止由呼叫端負責
|
||||
```
|
||||
|
||||
@@ -159,11 +189,11 @@ isEmptyOrNull('abc'); // false
|
||||
<a id="requirevalue"></a>
|
||||
### requireValue
|
||||
|
||||
檢查必填值。先以 `[INFO]` 印出 `name=value`，若值被判定為空則印出 `[ERR]` 並以 exit code 1 結束程序。
|
||||
檢查必填值。先以 `[INF]` 印出 `name=value`，若值被判定為空則以 `[ERR]` 輸出並以 exit code 1 結束程序。
|
||||
|
||||
```js
|
||||
requireValue('GITEA_SERVER_URL', process.env.GITEA_SERVER_URL);
|
||||
// 值為空 → 輸出 [ERR] GITEA_SERVER_URL is required，並 process.exit(1)
|
||||
// 值為空 → 輸出 [ERR][時間]: GITEA_SERVER_URL is required，並 process.exit(1)
|
||||
```
|
||||
|
||||
> 前置條件：應在程式啟動早期呼叫。注意此函式會將值原樣印到 stdout，故不用於機密值（程式對 `GITEA_TOKEN` 改以 redacted 方式輸出）。
|
||||
@@ -171,11 +201,11 @@ requireValue('GITEA_SERVER_URL', process.env.GITEA_SERVER_URL);
|
||||
<a id="requireinteger"></a>
|
||||
### requireInteger
|
||||
|
||||
驗證值是否為非負整數字串（正則 `/^[0-9]+$/`，允許前導零、不允許負號或小數），不符合時印出 `[ERR]` 並以 exit code 1 結束程序。
|
||||
驗證值是否為非負整數字串（正則 `/^[0-9]+$/`，允許前導零、不允許負號或小數），不符合時以 `[ERR]` 輸出並以 exit code 1 結束程序。
|
||||
|
||||
```js
|
||||
requireInteger('KEEP_COUNT', '2'); // 通過
|
||||
requireInteger('KEEP_COUNT', '-1'); // 輸出 [ERR] ... 並 process.exit(1)
|
||||
requireInteger('KEEP_COUNT', '-1'); // 輸出 [ERR][時間]: ... 並 process.exit(1)
|
||||
```
|
||||
|
||||
<a id="isbeta"></a>
|
||||
@@ -204,4 +234,4 @@ main().catch((err) => {
|
||||
});
|
||||
```
|
||||
|
||||
> 前置條件：執行環境須提供必要環境變數，且可連線到 Gitea API。結果：清理符合條件的舊 release 與孤兒 tag，並輸出處理過程 log。
|
||||
> 前置條件：執行環境須提供必要環境變數，且可連線到 Gitea API。結果：清理符合條件的舊 release 與孤兒 tag，並以統一等級式日誌輸出處理過程。
|
||||
|
||||
Reference in New Issue
Block a user