版本號怎麼升？語意化版本與 CHANGELOG 入門

三個月後你不會記得哪個版本加了什麼功能，除非有人幫你記。版本號和 CHANGELOG 就是那個記憶外掛：版本號讓你知道自己改了什麼，CHANGELOG 讓客戶和使用者也知道。這篇帶你搞懂語意化版本怎麼升、CHANGELOG 怎麼寫，以及完整的 Git Tag 發布流程。

語意化版本：MAJOR.MINOR.PATCH

什麼時候升版本號

CHANGELOG 的格式

# Changelog

## [1.1.0] - 2026-06-28
### Added
- 加入查詢歷史記錄功能（GET /api/history）
- 使用者可以刪除自己的查詢記錄
### Fixed
- 修正城市名稱大小寫不一致導致快取失效的問題

## [1.0.0] - 2026-06-01
### Added
- 天氣查詢功能（GET /weather/{city}）
- 使用者帳號系統（JWT 認證）

Git Tag 發布流程

# 1. 確認程式碼準備好了（測試通過）
git status

# 2. 更新 CHANGELOG.md

# 3. 更新版本號（pyproject.toml 或 __init__.py）

# 4. Commit 版本變更
git add CHANGELOG.md pyproject.toml
git commit -m "chore: bump version to 1.1.0"

# 5. 打 Tag
git tag -a v1.1.0 -m "v1.1.0: 加入查詢歷史功能"

# 6. Push 含 Tag
git push origin main --tags

# 查看所有 Tag
git tag -l

# 回到某個版本
git checkout v1.0.0

在 FastAPI 顯示版本資訊

# pyproject.toml
[tool.poetry]
version = "1.1.0"

# main.py
from importlib.metadata import version

app = FastAPI(
    title="天氣小工具",
    version=version("weather-app"),
    description="查詢即時天氣的 RESTful API"
)

延伸：Conventional Commits 讓 commit 訊息有意義

Conventional Commits 是一個 commit 訊息的規範，格式是 type(scope): description，讓 commit 記錄可讀性更高，也能自動生成 CHANGELOG。