我心中 Release note 與 changelog 在產品中應用的差異

簡單聊聊 Release notes 跟 changelog

Kiwi lee
5 min readJun 4, 2022

最近公司在推行自動化所有服務,其中就有包含發佈新 Platform tools 的更新日誌,要以怎樣的方式來呈現,我有被需求訪談,但仔細想了下,發現每家公司適合的都不一樣,因此這邊想要提出我對於這兩個發佈的想法,可以合在一起,也可以只選擇一個來分佈即可。

Changelog

在我心中,changelog 主要是針對目前系統的開發者,出發點是更直接的描述新的版本跟舊的版本「在程式面上的不同之處」,所以會提到更多的 added/fixed/changed/refactor 之類的項目,甚至直接跟 Issue/Pull reqeust 做連接。

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2017-06-20
### Added
- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help translation authors keep things up-to-date.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03
### Added
- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can
benefit both "open" and "closed" source proj

這塊我個人是覺得,如果透過 pipeline 自動生成的 changelog 會是最完美的,透過 label 來定義此 PR 的類型,對應 milestone 則視為系統版本,而 PR 的標題就是到時 changelog 上面的文字。

Keep a Changelog

Release Note

建議每個軟體產品都要有這個。

Release note 我覺得重點在於是給人看的,不只是使用你產品的客戶,更包括在你公司的 PM 或老闆,透過這個可以很迅速的知道產品的差異,例如:

  • 與舊版本之間的衝擊要如何的去調整
  • 有哪新的功能可以優化我們使用上的體驗
  • 系統效能上的提升

此外,如果是對外的產品,這也是個很好的機會跟你們的使用者溝通,展現你們公司的文化。我覺得在這點上,VSCode 就做得蠻好的 (上面圖也是 2022.04 vscode 的 release note),除了文字的介紹外,他們還做了影片介紹,有趣的是還有短版的 60 秒,專門給手機使用者聆聽的直版畫面,很有趣。

Visual Studio Code April 2022

結論

不管最後採用哪種,我相信都會是對開發上很大的幫助,可協助定義開發進度,甚至出問題的時候,還可以先簡單的回顧可能是哪個版本所引發。即使軟體只在內部中使用,透過版本號的說明,在講解系統功能,及討論內部平台之間的相容性,也很容易可以聚焦起來,而不是透過散落的 PR,一個一個 commit 在 git log 中迴遊找尋。這個之前有體驗過,要不是系統還在草創,不然真的哭到在地,開始準備看明天的日出了。

參考網站

Changelog vs Release Notes: What’s the Difference? (announcekit.app)

The Difference Between A Changelog and a Release Note — Bitband Blog

A Beginner’s Guide to Git — What is a Changelog and How to Generate it (freecodecamp.org)

--

--

Kiwi lee
Kiwi lee

Written by Kiwi lee

Hi, I'm kiwi, Platform Engineer (SRE, DevOps). Python Engineer. Love art, books, longboard. https://kiwi-walk.com

No responses yet