版本說明,別再發版時才重寫

最近替自己的樂譜練習 App LilyScore 準備發版,功能做完、測試也跑過,最後卻卡在一個很普通的問題:這版到底更新了什麼?

過程中加過播放器功能、修過樂譜庫,還順手調了幾個小地方。每個當下我都知道自己在做什麼,隔了幾天再回頭看,腦袋卻只剩下「好像改了播放器」、「還有一個 bug」。接著又開始翻 commit、issue 和對話紀錄,把剛做完的事情重新整理一次。

LilyScore 第一次走完整個上架流程時,我才發現每一版都會遇到同一件事。商店要一份讓練習的人看得懂的更新說明,GitHub Release 又要保留完整紀錄;兩份都靠發版前臨時回想,很像考前一天才開始整理筆記。而且還是自己出的題目。

後來我沒有再多維護一份版本說明文件,而是把平常留下的修改紀錄,直接拿來當發版時的原料。

先留下可讀的修改紀錄

Git 是程式專案常用的版本管理工具;commit 則是每次保存一小段修改時,替那次變更留下的紀錄。tag(版本標記)是替某個版本做的記號,從上一個發版 tag 往後看,就能找出這一版新增了哪些修改。

如果目前還沒有發版腳本,先手動做一次就夠了:

  1. 找到上一個發版的 tag。
  2. 列出那個 tag 到現在的 commit。
  3. 挑出使用者會在意的功能與修正,改寫成幾行版本說明。

例如上一版是 v2.2.0,可以先用下面這行列出後續的 commit 標題:

1
git log v2.2.0..HEAD --pretty=%s

這裡還不用急著自動化。先讓每次修改都留下一句能看懂的紀錄,發版時就不必從聊天紀錄裡考古。如果你還沒用 Git,同樣可以把紀錄放在待辦清單或更新筆記裡,只要它能回答「上次發布後,我做了什麼」就行。

兩份版本說明

同一批 commit,我會整理成兩份內容。短版給實際使用 App 的人看,只留下多了什麼、修了什麼;完整版留給以後的我,連文件、測試與發版過程都保留。以 LilyScore 為例,短版放到 Google Play,完整版放到 GitHub Release,也就是 GitHub 上每個版本的發布頁。

為了讓腳本分得出哪些修改值得對外說,我在新增功能的標題前加上 feat:,修正問題則用 fix:。這只是平常寫紀錄時採用的分類,先有一致的寫法,發版時才有規則可以篩選。

去哪裡 取哪些內容 用來做什麼
Google Play 新增功能與問題修正,篩選後再確認文字 讓使用者知道這版增加與修正了什麼
GitHub Release 版本範圍內的所有 commit 標題與短編號 讓自己日後追查每一筆修改

不過,拿掉前綴還不一定能直接放上商店。LilyScore 真的有過下面兩筆 commit,自動整理只會做到中間那欄;右邊是我把同一件事改寫給使用者看的示例,並非腳本會自動產出的文字。

原始 commit 自動整理的候選文字 人工改寫示例
feat(player): A-B 循環在進度條上可視化 A-B 循環在進度條上可視化 在播放進度條上顯示 A-B 循環範圍,方便查看反覆播放的起點與終點。
fix(home): 空狀態不再放浮動按鈕,「匯入樂譜」不重複出現 空狀態不再放浮動按鈕,「匯入樂譜」不重複出現 修正尚未匯入樂譜時,畫面重複出現「匯入樂譜」按鈕的問題。

「空狀態」對寫程式的人很直覺,使用者卻要先猜它指的是哪個畫面。腳本能幫我找出這筆修正,換成對方看得懂的說法,仍然要由我決定。GitHub Release 則保留原本的標題、前綴與短編號,連文件、雜項維護和發版本身的 commit 都列出;要看實際改了哪些程式,再點進 commit。

這張圖把人工確認也列進流程,這一步目前仍要在發版指令前手動完成。



flowchart TD
    A[留下可讀的修改紀錄] --> B[選定本次更新範圍]
    B --> C[挑出新功能與問題修正]
    C --> D[人工確認與改寫]
    D --> E[Google Play 短版]
    B --> F[保留所有修改標題]
    F --> G[GitHub Release 完整版]

Commit 標題要寫給人看

當 commit 標題有可能出現在商店裡,我就不能再寫「fix bug」、「調整一下」或「final final 真的 final」。以前這種標題只會讓幾週後的我看不懂,現在還可能直接變成使用者看到的版本說明,丟臉範圍變大了。

這也是我最喜歡的副作用。版本說明的品質,早在每次保存小改動時就決定了一部分。如果你讓 AI 幫忙寫 commit,也要看一眼「這個改動要怎麼講給人聽」。否則只會得到一串文法很完整,卻不知道做了什麼的句子。

當然,不是所有 commit 都適合對外說。重構、調整測試、修 CI,可能對維護很重要,卻不一定是練習的人需要知道的更新。所以我只把 feat: 和 fix: 當成商店候選內容;你也可以使用自己的分類,先決定哪些變更值得出現在使用者面前即可。

LilyScore 的發版流程

我後來把固定步驟放進 scripts/release.ps1。它會檢查目前是不是在主分支 main、有沒有已追蹤但尚未提交的修改、本機是否落後遠端、tag 是否重複,再檢查程式是否有靜態分析能找出的錯誤。通過後,腳本更新版號與建置編號、整理 Play 說明,接著建立 release commit、tag 並推上 GitHub。後續測試、簽章建置與上傳,交給 GitHub Actions 自動執行,這就是下面提到的 CI。

發版前先確認文字

這裡還有個目前腳本沒補上的步驟。它會在終端印出版本說明,接著直接 commit、打 tag 並 push,沒有停下來等我確認。因此,要先檢查文字,就得在執行發版指令之前,用前面的 git log 列出修改、整理好內容,再用 -Notes 傳入已確認的版本說明。例如只要說明這次循環範圍的更新,可以在 LilyScore 專案裡執行:

1
.\scripts\release.ps1 -Version 2.3.0 -Notes '在播放進度條上顯示 A-B 循環範圍。'

這樣會覆寫自動彙整的文字,並繼續完成發版;它是一條會提交和推送的指令。腳本也有 -NoPush 參數,但那仍會建立 commit 與 tag,只省略推送,不能當成單純預覽。想把「產生候選文字、人工確認、正式送出」接成不中斷的流程,還需要替腳本補上預覽與確認步驟。

測試版的更新範圍

兩份紀錄還有個小差別,從哪個版本開始算。假設上次送到 Play 的版本是 v2.2.0,中間做過 v2.3.0-alpha.1 與 v2.3.0-beta.1,現在準備送出 v2.3.0,商店說明應該包含整段測試期間累積的功能。GitHub Release 則每個測試版都有紀錄,可以分開追查這幾次修改。

LilyScore 因此把名稱含 - 的 tag 視為測試版,只建立 GitHub Release;不含 - 才送進 Play 封閉測試軌道,讓加入測試的人收到更新,這不代表已經發布到正式軌道。Play 說明從上一個不含 - 的 tag 開始,GitHub Release 則取排除本次 tag 後、依版本號排序的第一個 v* tag 作為起點。這是我目前專案的分流規則,其他專案可以按自己的發布方式調整。

自動彙整的四個邊界

沒有 feat: 或 fix:

這版若找不到 feat: 或 fix:,腳本目前會放入「穩定性與效能改善。」這句備用文字,避免產生空白說明。但這句話未必有 commit 可以證明;更保守的做法是中止發版,要求人工補上內容。目前腳本還沒這樣做,需要在執行前確認這版改了什麼,再用前面的 -Notes 傳入合適的文字。

內容超過商店上限

Google Play 的 Prepare and roll out a release 說明目前允許每種語言最多 500 個 Unicode 字元。我的腳本依新到舊逐條放入,快滿時就停止。它用 PowerShell 的字串長度做較保守的檢查,純中文通常不受影響,emoji 可能提早碰到限制;大改版仍會改用手寫說明。

tag 畫錯版本範圍

目前的腳本依版本號排序找上一個 tag,前提是 release tag 都在同一條主線,版號也一直往上增加。如果專案同時維護多條版本分支或做 backport,就該限制為目前 HEAD 的祖先 tag,否則 git log A..HEAD 可能抓錯版本。重寫 Git 歷史、壓縮 commit 或把 tag 打錯位置,也會改變輸出。

CI 讀不到舊紀錄

actions/checkout 預設只抓觸發 workflow 的一個 commit,runner 可能根本沒有舊 tag。本來要列整段變更的 git log,最後就只剩本次 commit;LilyScore 因此把 fetch-depth 設為 0,讓 CI 取得完整歷史。這類問題平常不容易出現,通常會挑發版那天才突然讓人想把電腦闔起來。


版本說明最後還是得由我看過,因為讀者不是 CI,也不會因為內容由腳本產生就突然看得懂。有了平常留下的紀錄,發版時可以從這份清單挑選、改寫,不必再從空白頁開始回想。

把已經寫在 commit 裡的資訊再整理一次,聽起來很勤勞,實際上只是我以前還沒想到要偷懶而已。