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

統一日誌格式與文件化，新增容錯回退、sha 已標記檢查與 v 前綴支援 #4

Merged
admin merged 7 commits from develop into master 2026-07-16 05:35:59 +00:00
Conversation 1 Commits 7 Files Changed 8
+906 -402
jiantw83 commented 2026-07-16 05:10:38 +00:00
Member
Copy Link
Copy Source

變更摘要

執行 /jsc:doc-funcs 文件化流程的完整成果：統一日誌輸出格式、補齊指令檔逐行註解、重建 README，並將先前未進版控的 src/logger.js、src/version.js 納入追蹤。另新增兩項行為：

  1. 容錯回退：git tag 讀取失敗（例如 workflow 未先執行 actions/checkout）時輸出 ERR 說明後，改以起始版號 0.0.1（beta 為 0.0.1-beta.1）作為預設值繼續輸出，不再以未捕捉例外崩潰。
  2. 已標記檢查：新增選填輸入 sha（建議傳入 ${{ gitea.sha }}，未提供時自動改用 GITHUB_SHA）；該 commit 已有符合格式的版號 tag 時直接輸出該 tag 內容（多個取最大、忽略 is_beta），不再計算下一版；sha 無效時輸出 WRN 後改走一般計算流程。
  3. v 前綴支援：版號 tag 可帶小寫 v 前綴（如 v1.2.3），解析時只取 v 之後的版本號；輸出的 value 一律不帶前綴。

影響範圍

  • 日誌格式（行為可見變更）：所有輸出訊息由 [時間][階段][等級]: 訊息 改為 [階段][等級][時間]: 訊息（階段 選填、等級 為 INF/WRN/ERR/TRC/DBG、時間 為 Asia/Taipei 的 yyyy/MM/dd HH:mm:ss）。版號計算邏輯與 action 輸出 value 完全不變。
  • 檔名調整：readme.md → README.md；容器建置檔定案為小寫 dockerfile，與 action.yml 的 image: dockerfile 引用一致。

重點檔案

檔案 變更
src/logger.js format() 組字順序改為階段在前；全模組 JSDoc 與範例同步更新（新進版控）
src/version.js 版號解析／比較／進位模組，完整 JSDoc（新進版控）；parse() 接受小寫 v 前綴
src/index.js JSDoc 日誌範例更新為新格式；findLatestVersion() 讀 tag 失敗時輸出 ERR＋WRN 後回傳 null（回退起始版號）；git() 的 stderr 改為擷取、錯誤詳情摺疊為單行併入統一格式訊息；新增 readSha() 與 findVersionAtCommit()，main() 先做已標記檢查再計算
entrypoint.sh 三行啟動訊息改用新格式、標頭更新時間刷新、加上執行權限（100755）
action.yml 新增用途／更新時間標頭與逐行繁中註解；新增選填輸入 sha；其餘設定值不變
dockerfile 標頭更新時間刷新，指令本體不變
README.md 重建：新增日誌格式說明、功能列表行號連結修正、更新時間刷新；補充讀 tag 失敗回退起始版號的行為說明

驗證

  • node --check 三個 JS 模組、sh -n entrypoint.sh、YAML 解析全部通過。
  • 以臨時 git repo 實測三情境：1.2.4-beta.3 → 1.2.4（轉正式）、→ 1.2.4-beta.4（beta 續號）、非法 is_beta 以 exit 1 結束，日誌皆為新格式。
  • 已標記檢查六情境：已標記直接輸出（忽略 is_beta）、未標記照常計算、無效 sha WRN 回退、GITHUB_SHA 回退來源、同 commit 多 tag 取最大、皆空略過檢查。
  • README 錨點一致性檢查 9/9 通過。

風險與注意事項

  • 日誌格式變更會影響任何解析 workflow log 的既有工具（若有）。
  • 讀 tag 失敗改為輸出預設值 0.0.1 且 exit 0：若正式環境忘了 checkout，job 不會失敗，後續步驟可能拿 0.0.1 打 tag；ERR/WRN 訊息會留在 log 供辨識。
  • repo 現有 v0.0.1 tag：v 前綴支援後可正常識別（該 commit 的已標記檢查會輸出 0.0.1、下一版為 0.0.2）。
  • entrypoint.sh 啟動訊息中的時間為寫檔時的固定字串（非執行當下時間），檔內已註解標註。
  • Docker 映像未實際重新建置（dockerfile 指令本體與先前相同，僅註解時間更新）。

🤖 Generated with Claude Code

## 變更摘要 執行 `/jsc:doc-funcs` 文件化流程的完整成果：統一日誌輸出格式、補齊指令檔逐行註解、重建 README，並將先前未進版控的 `src/logger.js`、`src/version.js` 納入追蹤。另新增兩項行為： 1. **容錯回退**：git tag 讀取失敗（例如 workflow 未先執行 actions/checkout）時輸出 ERR 說明後，改以起始版號 `0.0.1`（beta 為 `0.0.1-beta.1`）作為預設值繼續輸出，不再以未捕捉例外崩潰。 2. **已標記檢查**：新增選填輸入 `sha`（建議傳入 `${{ gitea.sha }}`，未提供時自動改用 `GITHUB_SHA`）；該 commit 已有符合格式的版號 tag 時直接輸出該 tag 內容（多個取最大、忽略 `is_beta`），不再計算下一版；sha 無效時輸出 WRN 後改走一般計算流程。 3. **v 前綴支援**：版號 tag 可帶小寫 `v` 前綴（如 `v1.2.3`），解析時只取 `v` 之後的版本號；輸出的 `value` 一律不帶前綴。 ## 影響範圍 - **日誌格式（行為可見變更）**：所有輸出訊息由 `[時間][階段][等級]: 訊息` 改為 `[階段][等級][時間]: 訊息`（`階段` 選填、`等級` 為 INF/WRN/ERR/TRC/DBG、`時間` 為 Asia/Taipei 的 `yyyy/MM/dd HH:mm:ss`）。版號計算邏輯與 action 輸出 `value` 完全不變。 - **檔名調整**：`readme.md` → `README.md`；容器建置檔定案為小寫 `dockerfile`，與 `action.yml` 的 `image: dockerfile` 引用一致。 ## 重點檔案 | 檔案 | 變更 | | --- | --- | | `src/logger.js` | `format()` 組字順序改為階段在前；全模組 JSDoc 與範例同步更新（新進版控） | | `src/version.js` | 版號解析／比較／進位模組，完整 JSDoc（新進版控）；`parse()` 接受小寫 `v` 前綴 | | `src/index.js` | JSDoc 日誌範例更新為新格式；`findLatestVersion()` 讀 tag 失敗時輸出 ERR＋WRN 後回傳 null（回退起始版號）；`git()` 的 stderr 改為擷取、錯誤詳情摺疊為單行併入統一格式訊息；新增 `readSha()` 與 `findVersionAtCommit()`，main() 先做已標記檢查再計算 | | `entrypoint.sh` | 三行啟動訊息改用新格式、標頭更新時間刷新、加上執行權限（100755） | | `action.yml` | 新增用途／更新時間標頭與逐行繁中註解；新增選填輸入 `sha`；其餘設定值不變 | | `dockerfile` | 標頭更新時間刷新，指令本體不變 | | `README.md` | 重建：新增日誌格式說明、功能列表行號連結修正、更新時間刷新；補充讀 tag 失敗回退起始版號的行為說明 | ## 驗證 - `node --check` 三個 JS 模組、`sh -n entrypoint.sh`、YAML 解析全部通過。 - 以臨時 git repo 實測三情境：`1.2.4-beta.3` → `1.2.4`（轉正式）、→ `1.2.4-beta.4`（beta 續號）、非法 `is_beta` 以 exit 1 結束，日誌皆為新格式。 - 已標記檢查六情境：已標記直接輸出（忽略 is_beta）、未標記照常計算、無效 sha WRN 回退、`GITHUB_SHA` 回退來源、同 commit 多 tag 取最大、皆空略過檢查。 - README 錨點一致性檢查 9/9 通過。 ## 風險與注意事項 - 日誌格式變更會影響任何解析 workflow log 的既有工具（若有）。 - 讀 tag 失敗改為輸出預設值 `0.0.1` 且 exit 0：若正式環境忘了 checkout，job 不會失敗，後續步驟可能拿 `0.0.1` 打 tag；ERR/WRN 訊息會留在 log 供辨識。 - repo 現有 `v0.0.1` tag：v 前綴支援後可正常識別（該 commit 的已標記檢查會輸出 `0.0.1`、下一版為 `0.0.2`）。 - `entrypoint.sh` 啟動訊息中的時間為寫檔時的固定字串（非執行當下時間），檔內已註解標註。 - Docker 映像未實際重新建置（dockerfile 指令本體與先前相同，僅註解時間更新）。 🤖 Generated with [Claude Code](https://claude.com/claude-code)
jiantw83 added 7 commits 2026-07-16 05:10:38 +00:00
refactor: 統一日誌格式為 [階段][等級][時間] 並補齊指令檔文件與 README
docker-actions/template: CI / BUILD (pull_request) Successful in 4s
Details
1773c646d5 
- logger.js format() 組字順序改為階段在前、等級居中、時間在後（Asia/Taipei）
- entrypoint.sh 啟動訊息改用新格式並更新標頭時間
- action.yml 新增用途/更新時間標頭與逐行繁中註解，設定值不變
- dockerfile 檔名維持小寫並與 action.yml 的 image 引用一致
- 新增 src/logger.js、src/version.js 模組與完整 JSDoc；重建 README.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
feat(讀取版號): git tag 讀取失敗時輸出 ERR 並改以起始版號 0.0.1 作為預設值 8dfce93271 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(README): 補充 git tag 讀取失敗時回退起始版號的行為說明
docker-actions/template: CI / BUILD (pull_request) Successful in 1m3s
Details
76a896c306 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
feat(檢查已標記): 新增 sha 輸入，commit 已有版號 tag 時直接輸出該版號 19a8667962 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(README): 補充 sha 輸入與已標記檢查的使用方式與規則
docker-actions/template: CI / BUILD (pull_request) Successful in 2s
Details
ea75d1adcd 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
feat(版號解析): parse 接受小寫 v 前綴，只取 v 之後的版本號 9f6c2a2556 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs(README): 補充 v 前綴 tag 支援與範例、修正功能列表行號連結
docker-actions/template: CI / BUILD (pull_request) Successful in 3s
Details
98a447beb1 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
admin approved these changes 2026-07-16 05:35:56 +00:00
admin merged commit b5b2739b7f into master 2026-07-16 05:35:59 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
admin
Labels
No items
No labels
Milestone
No items
No Milestone
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: docker-actions/calculate-next-version#4