Node快閃：npm模塊版本策略

02-05

我們繼續之前的Node快閃：發布你自己的npm模塊，以及Node快閃：用mocha測試你的npm模塊的教程，來講解一下npm模塊的版本策略。

npm採用semver標準（semver 文檔在這裡），簡單總結如下：

採用semver的軟體必須聲明可以調用的API

version以x.y.z為格式，x, y, z為非負整數。x稱作major，y稱作minor，z稱作patch。

一旦一個version的代碼被發布以後，代碼的內容絕對不能改變，任何修改必須以新的version發布

major為0的的版本用作初始開發用，任何邏輯，功能在這段時間都可以改變，API這時不是穩定的

version 1.0.0 為正式API，1.0.0以後version的變動根據API需求而變

patch version為bug fix，bug fix應該是內部的邏輯變化，顧名思義修復bug

minor version也被稱為feature version，指的是API新添加了一個與現有API兼容的功能。

major version也被稱為breaking version，指的是API做出了不兼容的改變。

pre-release版本是通過在x.y.z後面追加「-[0-9A-Za-z]」的字元串，比如1.0.0-alpha, 1.0.0-beta.1等

更多細節請參考semver文檔。

之前我們在Node快閃：發布你自己的npm模塊中運行npm init的時候，細心的讀者會發現如果我們接受默認選項，在生成的package.json中的version是1.0.0，而我們在彈出的version項中輸入了0.0.1。原因就在於我們一開始開發模塊的時候，往往處於初始／試驗階段，等到API成熟以後再發布1.0版本。

我們發布的模塊version還處於0.0.1，嚴格來講其實是不正確的，因為這時候我們的模塊已經有了一個feature。所以我們現在來發布第一個minor version。

在這裡我們可以用npm自帶的命令：npm version。這個命令會根據用戶輸入，自動更新package.json中的version項，添加一個git commit，並且添加一個git tag。你接下來需要做的只不過是用git push將生成的commit和tag同步到git，再用npm publish將更新的版本發布到npm上。

寫這篇文章的時候，我們已經對代碼進行了三次改變：

1. Node快閃：發布你自己的npm模塊 - 添加了最基礎的addFn的API - minor version

2. Node快閃：用mocha測試你的npm模塊 - 添加了現有API的測試，並修復了一個所謂的「bug」：對於非數字的輸入，我們返回NaN - patch version

3. Node快閃：測試驅動開發（TDD）npm模塊 - 添加了更多對現有API的測試，並改變了API的行為：對於addFn(1)(a)，輸出null，對於addFn(non-number)，拋出Error - 而且我們認為這時候API應該穩定了 - major version

注意在以上第3步，理論上，我們的API做出了不兼容的改變，所以應該是一個major version，不過由於我們處於0.y.z的試驗階段，如果我們覺得API還沒有穩定，可以進行一個minor version的發布。

現在我們分別進行以上minor，patch，major的發布。

1. checkout （1）中的代碼，運行npm version，並進行同步和發布。

$ git checkout npm-modulen$ npm version minor -m "initial addFn functionality"n$ npm publishn$ git push origin v0.1.0n

現在你可以驗證自己發布的npm模塊，運行

npm view <your-module-name>@0.1.0n

你也可以查看查看自己的github的repo，查看自己剛同步的tag

可以看到，「initial addFn functionality」就是我們之前運行npm version的-m選項。

2. checkout（2）中的代碼，進行上文中的patch version

$ git checkout mocha-basicsn$ npm version 0.1.1 -m "%s add mocha tests, non-number input returns NaN"n$ npm publishn$ git push origin v0.1.1n

注意上面我們直接輸入了0.1.1，這是因為我們在追加version，在我們git checkout mocha-basics的時候，package.json裡面的version被重置為0.0.1，這時如果我們運行npm version patch，就會被錯誤的更新成0.0.2。所以這裡一個實戰經驗是，盡量在master branch裡面進行所有npm version的升級。

3. （3）中的代碼其實是我們的master branch的最近的一點，所以，這裡我們直接在master上面進行version update。

$ git checkout mastern$ npm version 1.0.0 -m "%s addFn(non-number) throws Error, stable API"n$ npm publishn$ git push origin master v1.0.0n

注意上面在npm version 的 -m 選項中我們放入了一個%s的佔位符，這個佔位符其實會被最後生成的semver值代替，出現在git tag的message中。

最後我們成功地生成了三個git tag。注意所有生成的tag都是semver值前面加了一個v，這是npm version的默認行為，是完全沒有問題的。

現在你已經掌握了基本的npm 模塊版本策略和管理。我們總結一下本篇教程用到的基本知識：

# semver以x.y.z為格式，x為major，y為minor，z為patchnn# npm version [major|minor|patch|semver] -m "%s message"nn# npm version會生成計算好的semver，生成相應的commit和tag，n# 我們需要運行git push和npm publish同步到git和npmnn# 在不同的branch上追加version時，會出現version非線性的狀況，n# 可以直接輸入計算好的semver，n# 當然，實戰策略是在master branch得到更新後，儘快進行版本升級n