嗨產品人，我們可以有一份認真的 Changelog 嗎？

每一次軟體或 app 跳出更新通知時，你會關心到底更新了什麼嗎？如果你現在打開 App store 來看，應該很容易在新功能（What’s New）欄位看到「bug fixes and performance improvements」（錯誤修正和性能優化）。這句萬用公式在各大科技巨頭泛濫成災，始作俑者其實是 Instagram，他們大概也沒想到從此被當作 changelog 模板，¹ 讓開發者砲轟：「如果要這樣寫 changelog，還不如不要寫。」²

這篇論點引起科技人的廣大共鳴，也勾起我的好奇：沒有技術背景的使用者真的會在意 changelog 嗎？大家是怎麼看待 changelog 的？各方賦予它的意義是什麼？寫 changelog 又有哪些方法可循呢？我試著在探尋答案的過程中梳理這些資訊，並理解 changelog 的定位。

為什麼我們有必要認真對待 Changelog？

Changelog（更新／變更日誌，也有些寫法是 change log）記錄專案或軟體產品版本間的演進差異，通常是以時間軸倒敘呈現的條列式清單，最新的版本會在最上方，讓使用者和開發者簡單明瞭軟體更新改了什麼，以及為何要改。除了有些軟體或產品網站上有 changelog 專屬頁面，通常還可以在團隊公開新功能的部落格文章、GitHub repository 裡的「CHANGELOG.md」和應用程式商店的「What’s new」看到 changelog，這就要先說到大眾最眼熟的那句 changelog 了。

「bug fixes and performance improvements」的爭議在於已經淪為各家軟體的「預設值」——本質上是沒什麼意義的廢話，不然我幹嘛更新呢？那是修復了什麼 bug、又改進了哪一塊效能？你不說我不問好像變成了一種默契。然而，包括我這種外行人也會懷疑，沒有技術背景的一般使用者真的會看 changelog 嗎？或是，大家真的在乎嗎？

多數人可能只在意「有感」，像是更新後不要當機、閃退、app 運作更順暢等等，卻也不乏因為「bug fixes and performance improvements」而被陷害的悲劇——更新才發現整個界面根本就「回不去了」的那種背叛感，害有些比較念舊的使用者（不論是出於喜好或習慣）怒吼「早知道就不更新！」因此以非開源的軟體而言，一份健康的 changelog 尤其重要，因為沒機會回到舊版本了。（像是有些 app icon 每逢特定檔期便推出花俏的設計，凸顯自己的存在感 ⋯⋯）

科技巨頭簡陋的 changelog 是必要之惡？

時間回到 2018 年，蘋果在全球開發者大會（WWDC）後更新 App Store Review Guidelines，包括新增了 2.3.12 這一項規範：「App 必須在其『新功能』（What’s New）清楚描述新功能和產品的更改情況。一些簡單的錯誤修復、安全更新和性能改善（Simple bug fixes, security updates, and performance improvements）可以透過一般描述說明，但較為重大的更改必須明列於備註中。」³

雖然沒有指名道姓，但很容易聯想到那些老愛複製貼上萬用公式而長期為人詬病的巨頭。歐洲的 App 開發商 Shape 就對這次的更新下了註解：「有幾家大型的社群網路公司一直在產品的每個版本重複使用同樣的更新說明，然後針對使用者遠端開啟新功能。在新規定之下，這種做法可能不會再被默許。」⁴

這和 Hacker News 上不少網友點出的原因不謀而合。⁵ 所謂的「功能切換」（feature flag／feature toggle）系統可以為特定使用者開關功能——關閉狀態時前台使用舊程式碼邏輯；開啟狀態時則用新上線的程式碼邏輯——在不影響現有使用者體驗的情況下逐步上線、測試，再依據要驗證的目標決定分階段釋出的受眾。⁶

如果在對 1% 受眾釋出的階段觀察到錯誤，就 Rollback（回復上一動）到舊狀態，並在下個版本修復，避免直接讓所有使用者都直接更新，結果所有人一起當機；或透過 A/B testing 觀察重要指標的變動，像是 Google、Facebook、Pinterest、Uber 和 Spotify 等公司的產品，同時進行上百個功能測試的實驗很常見，這也使推出的新功能與應用程式商店的 “What’s new” 脫鉤，使用者體驗不一的情況下，changelog 可能變成扣分幫凶。網友對此建議，如果要和即將部署的版本一起發佈新功能，可以在 changelog 中清楚標示該功能是「已推出」或「即將推出」。 ⁷

Anne Hsiao 曾擔任團隊統整產品部署與上線流程的負責人，在〈產品上線管理：寫給 PM 的基本名詞解釋與工作流程〉分享：「隨著產品團隊長大，上線這件事情變得愈來愈複雜，因此會需要專門的人來負責，有些團隊中會有專職的 Release Manager、Delivery Manager 來管理，有些團隊則是由 Project Manager、Product Manager 一條龍來負責前期規劃、開發到最後上線，另外一些團隊則是將最後一哩路統一交給 QA Manager 來負責。」可以想像，這些坐擁千萬使用者的程式通常推出的更新來自跨單位貢獻，一個版本可能包含十幾個團隊的幾十個變更，除非有綜觀全局、專門把控更新上線的管理者，否則部門 VP 或 CTO 不可能掌握每一項細節，寫上「bug fixes and performance improvements」就是一張萬用的安全牌。

因為這些公司的產品多是面向大眾的 2C app，所以有人認為他們才會選擇最「輕描淡寫」的寫法，否則如果讓使用者感到困惑，反而給自己找麻煩。

若產品的使用者是以此維生的開發者，changelog 只寫著「bug fixes and performance improvements」很可能會害他們踩坑，開發者 Remy van Elst 就提到他工作流程被破壞的血淚經驗：「因為不是所有的改變都是變好，要告訴我到底哪些地方不一樣了。」

好好寫一份 changelog 給你的回饋這麼多

不論是出於哪一種不得已而為之，身為使用者雖能理解，但不一定要全盤接受。等不到健康的 changelog 就罷了，至少能點下更新按鈕的只有我們：除了關閉自動更新，主動了解並判斷每一次的更新內容對自己的影響程度，也是制衡「bug fixes and performance improvements」微小而堅定的力量。

而開發者作為對程式碼最熟悉的人，寫 changelog 相對枯燥呆板，很容易在工作任務上被優先往後推遲，但隨著其他 project 的增生，再怎麼強大的記憶力也會逐漸淡忘當時產品的開發細節，這時候 changelog 能成為複習的必備教材；或是團隊加入新成員時，有 changelog 才能幫助他們無痛接軌。

另外，Hacker News 上有網友提到，⁸ 如果一個產品缺乏完善的 changelog，可能是開發團隊在試圖掩飾能力不足或更深層的隱憂，包括沈重的技術債或組織本身問題導致新功能並未正常作用。所以發生 bug 或大規模當機等問題時，除了公開透明的面對，具體說明也很重要，例如比起只寫「修復可能破壞整個資料庫的錯誤」，「修復在安裝 libzip 1.3.3 或更早版本的系統上保存包含特定 trailing unicode 字符記錄時，關鍵數據被毀損的錯誤」這樣的內容會理想得多。好處是彰顯：

1. 開發者已經徹底調查問題
2. 問題範圍有限，不影響所有使用者（雖然可能是多數）
3. 之所以會發生這麼糟糕的錯誤、測試的時候沒有發現是可以理解的

一旦養成好好寫一份 changelog 的習慣，也會享受到強大的正向循環力量。在 Stripe 擔任 Staff Design Engineer 的 Jonnie Hallman 製作了 side project 「Cushion」，這是一款為自由工作者打造的 app，他已經在 Cushion 的 changelog 耕耘超過八年，每一行更新說明都是他親自敲下鍵盤而非自動化發佈。他認為上架更新後寫下 changelog 能藉機感謝提議該項功能或發現 bug 的使用者，這種感覺是很棒的。⁹ 也有開發者提到，把一項修復 bug 或上架新功能的待辦任務標記為「完成」（done）的成就感之大，藉由 changelog 再傳遞給更多人，那種滿足感和回饋也加倍了。

Changelog 對新創公司的影響尤其顯著

雖然 “release notes” 和 changelog 可以混用，但前者相對狹義，通常侷限於軟體發佈週期，後者涵蓋的範圍則更廣，程式碼變更之外的各類事件都屬於其中。所以新創公司透過 changelog 傳達明確穩定的發展訊息，不僅是為團隊的努力留下印記，對外也能收穫使用者信任甚至是吸引投資人青睞。

Linear 本身是軟體開發的管理工具，所以他們一開始就覺得分享 changlog 是很自然的事，也和大多數新創公司一樣成立早期使用者（early-adopter）的專屬群組（現在多半在 Discord 或 Slack 上），團隊一邊修復問題一邊分享更新背後的考量，這是一種在乎使用者聲音的表現。善用 changelog 也能驅動使用者為產品背書，據 CEO 暨共同創辦人 Karri Saarinen 所說，Linear 使用者有時還會分享 changelog 給不是使用者的同事或親友，發揮人人都是品牌大使的效益；另外，定期發佈 changelog 有助於傳達公司重視交付的信念，這對新創來說非常重要，不僅是為團隊慶祝喝采、激勵士氣，也對潛在人才釋出企業積極的吸引力。

透過 changelog 更能公開證明早期新創公司的執行力，投資人依此評估團隊是否正確契合、是否能在資金燒光前打磨出他們心中的產品。Karri Saarinen 就提到，Linear 遇到多數天使投資人和 VC 都說有持續關注他們的 changelog，且對他們的推展效率印象深刻，外界對這些更新的反應也逃不過他們的雷達，進一步驗證產品的價值所在。（延伸閱讀：回報進度好煩！Linear 要讓團隊專注在更重要的工作）

對外的 changelog 提升過往工作的價值，對內的 changelog 增加後續創造的價值。——新創 DoubleLoop 創辦人 Daniel Schmidt

Karri Saarinen 強調，除非是提升效能或改善使用者體驗，不然對外的 changelog 不需要交代每件事。雖然客戶不關心數據庫搬遷這類的變更，但內部會關心這是否可能導致網站故障，還有這些變更背後基於什麼商業考量、是成或敗，以及過程中的學習。而且以新進員工的角度來看，當進到一家新公司，如果能讀到前同事做了什麼與原因，有助於團隊未來做出更好的決策，所以對內的 changelog 就應該鉅細靡遺。

那麼開發者或團隊可以怎麼寫 changelog 呢？一份健康的 changelog 通常具備哪些元素？下一篇我會彙整新創公司的實務分享和開發者的建議，提供 changelog 撰寫的大補帖，以及各種幫你減輕生成 changelog 負擔的工具包，為產品爭取加分。敬請期待～

資料來源：
1. Startups, Write Changelogs
2. https://news.ycombinator.com/item?id=17631326

（文章代表圖：截自 Github）

本文依 CC 創用姓名標示 - 非商業性 - 相同方式分享 4.0 國際釋出