版本控管 (Version Control) 的目的：

1. 知道改動的範圍 (Scope)
2. 內部各單位的溝通界面
3. 問題追蹤的參考索引

以下的說明，是我在 2013 年對內部其他單位溝通時的內容，然後稍作調整，主要描述的是版本控管的目的以及方法。這概念跟 Artifact Management 有很直接的關係。

底下的內容，是 2013 年一部內部訊息，整理出來的，部分內容是停留在當年 (2013) 的狀況.

版本編號規則

Software 常用的 X.Y.Z 三碼規範以 “功能” 為主, 如下:

1. X: 代表新增 重大功能、無法向下相容 或者 重大架構變更, 或者行銷 Magic Number. 像最近的 iOS 7, 或者Android 3.x -> 4.x
   • iOS7: UI 全面扁平化
   • iOS8: 提供 Health, 以及 Wearable 的界面
2. Y: 每一碼表示增減 features / function
   • 向下相容，例如 6.1 跟 6.0 是相容的
   • 例如 iOS 6.0 -> 6.1, 或者最近的 Android 4.4
3. Z: 表示維護碼, 常見名稱是 patch, 或 Fixpack, Hotfix. 針對已經 release 的產品, 作重大 bug fix, 或者 language patch / support IME, 通常不會有大功能新增.
   • 維護碼更動表示沒有相容性問題, 也就是 1.8.1 和 1.8.2 的設定應該是相容, 且不需要合併 (Merge) 的.
   • IBM 稱 FixPack, Microsoft 稱 Hotfix
4. Q: 有些版本會有第四碼，用來表示 Patch，Patch 通常指的是跟軟體工程無關的功能
   • 語言支援
   • 文件版本

版號在專案開始就會定義, 例如 1.6.0, 軟體有 daily build or nightly build, 所以除了版號, 還會附帶:

• build id: 通常是時間戳記, 格式通常是 YYYYMMDD-HHmm
• revision: source control serial number, SVN 是 revision, git 是 hash code
• tag: 用來標記 debug / release / project code
  • project code: 像 android 4.4 代號是 KitKat, 讓人們容易識別的關鍵字
• customer id: 如果是做 case by case project, 通常也會有這個號碼.

我們只有 release build 會把 tag 放在 build 裡, release build info 會像這樣:

1
2
3

version: 1.6.0
revision: 32870
build: 20130830-1200_Luffy_Release

這個檔案是動態簽入的，兩個時間底要更改：

1. 專案新的階段開始，要更改版號、代號
2. 每次建置 (build) 都要帶入時間

底下是簡單的 Artifact Timeline 示意圖，配合 Build Artifact 的概念，每次回報都要精準且清楚。

其實更理想的應該是把 tag 放在獨立欄位, 最後產生的 image 可以變成有這樣的 naming: App_1.6.0-Luffy_b20130830-1200_r32870.ipa. 不過我一直沒有時間去調整, 後來就讓它繼續按這規則跑.

和很多硬體 or Firmware 管理方式不同的地方在於: 假設 App 1.6.0 新增 10 features, 測試不通過, 則繼續測試, 並不會調整版號. 因為版本號代表階段性的功能集合, 不是時間或 schedule 的概念.

Release 之後, branch 會 code freeze, 表示進入維護階段, 不可以任意更動. 如發現 重大 問題, 則調整為 1.6.1, 修復發現的bug, 重新 release process. 同時間會有另一 個 1.7.0 正在開發中.

使用一般的 App, 假設從 1.5.x 到 1.6.x, 即可知道多一些新功能. 看到 1.6.0 到 1.6.1 即可知道, 修復一些 bug, 沒增加功能. 這規則在大部份的 open source project 是通用的.

Firmware version control 的建議

針對 FW version control 部分, 幾點建議:

1. FW 版號由我們定義, Vendor不可以自行調整版號, 但一定要附上時間 / revision
2. FW 正式 release 與開發中的 development build, 要能夠區分.
3. Vendor 需要提供API, 讓我方 developer 可以取得版本相關訊息 (新device要先確認)
4. FW 能否從 development to release 由雙方共同決定
5. 我方須維護 FW 每個版本的 requirement, design document, change log, test report, bug list, release note
6. Vendor 要提供每次交付的測試報告, 同時把 FW image 交付給我方 PM
7. 來自於 Vendor FW images/Toolchain/Document/Tool, 我們要有儲存, 交付內部單位, 等管理的方式.
8. Vendor給我們的FW image, 相關內容要定義清楚:
   • 檔案壓縮格式: RAR or zip (RAR 需要 license)
   • 檔名格式: image: {APPNAME}_{VERSION}_{BUILD_ID}_r{REVISION}.zip, ex: ORZ2000_1.5.0_b20130808_r2345.rar
   • 交付內容: 壓縮檔裡包含 FW image, change log
   • Change log 內容格式

這段是針對 Firmware version 的控管討論

結論

中間 FW 的建議, 是因為當時我們維護的 device 數量很多 (大大小小快二十個), 間接的 vendor 很多, 大部份的 vendor 對 version control 沒什麼規則與概念, 後來我直接強力介入, 要求統一定義, 然後 push 相關的窗口跟 vendor 溝通, 後來才統一 Software/Firmware version control 的規則.

補充 (Updated: 2018/05/20)

版本管理 是一個軟體開發過程中溝通必要的 介面，號稱在做軟體，但是卻不重視這些溝通介面，基本上是不及格的。下圖是 VSCode 的 Release Notes 描述，想想你們公司怎麼對外描述 Release Notes？

基本上，到一家新公司，從溝通的方法、介面，大概就能知道這家公司軟體開發成熟度的到哪了。

補充二

後來我知道，這篇文章講的東西叫做 Semantic Versioning。

延伸閱讀

站內文章

• 導入 CI/CD 的第一步
• 如何有效的回報問題 (How to Report Problems Effectively)
• 協同合作系統建制與導入 - 以 Redmine 為例
• 溝通 = 成本
• Software Development Lifecycle
• Artifacts Management
• 聊聊軟體交付的濫觴 談產出物管理 (Artifacts Management)

• Designing Test Architecture and Framework

參考資料

• Semantic Versioning
• 語意化版本
• 語意明確的版本變更
• Version Numbers for Continuous Delivery with Maven and Docker