standard version

標準版本

standard-version被棄用。如果您是GitHub用戶，我建議您釋放 - 替代方案。如果您無法使用github操作，或者由於某些其他原因需要堅持使用standard-version ，則可以使用standard-version的提交和標籤叉。

使用SEMVER和ChangElog生成的實用程序，該實用程序由傳統提交提供動力。

有問題？想貢獻嗎？加入我們的節點 - 動靜社區懈怠。

它的工作原理：

1. 遵循存儲庫中的常規提交規範。
2. 準備發佈時，請運行standard-version 。

然後， standard-version將執行以下操作：

1. 通過查看packageFiles [1]來檢索存儲庫的當前版本，回到最後一個git tag 。
2. 根據您的提交，在bumpFiles [1]中bump版本。
3. 根據您的提交生成一個changelog （在引擎蓋下使用常規變性）。
4. 創建一個新的commit ，包括您的bumpFiles [1]和更新的ChangElog。
5. 使用新版本編號創建一個新tag 。

bumpFiles ， packageFiles和updaters

standard-version使用一些關鍵概念來處理項目中的版本。

• packageFiles - 用戶定義的文件，可以從中讀取版本並“顛簸”。
  • 示例： package.json ， manifest.json
  • 在大多數情況下（包括默認）， packageFiles是bumpFiles的子集。
• bumpFiles - 用戶定義的文件，其中應“凸起”版本，但不明確閱讀。
  • 示例： package-lock.json ， npm-shrinkwrap.json
• updaters - 簡單的模塊，用於讀取packageFiles和寫入bumpFiles 。

默認情況下， standard-version假設您正在基於Nodejs的項目中工作...因此，對於大多數項目，您可能永遠不需要與這些選項進行交互。

也就是說，如果您發現自己詢問如何使用標準版本來獲取其他元數據文件，語言或版本文件？ - 這些配置選項將有所幫助！

安裝standard-version

作為本地npm run腳本

安裝並添加到devDependencies ：

 npm i --save-dev standard-version

將npm run腳本添加到您的package.json ：

{
  "scripts" : {
    "release" : " standard-version "
  }
}

現在，您可以使用npm run release代替npm version 。

這具有使您的回購/軟件包更便宜的好處，以便其他開發人員可以剪裁版本，而無需在其機器上全球安裝standard-version 。

作為全球bin

全球安裝（添加到您的PATH ）：

 npm i -g standard-version

現在，您可以使用standard-version代替npm version 。

這具有允許您在任何回購/軟件包上使用standard-version的好處，而無需向每個倉庫添加DEV依賴關係。

使用npx

從[email protected]開始， npx與npm一起安裝。使用npx npx standard-version可以使用standard-version ，而無需保留package.json 。

當在非JavaScript項目中使用standard-version時，此方法特別有用。

配置

您可以standard-version ：

1. 在您的package.json中放置一個standard-version節（假設您的項目是JavaScript）。
2. 創建.versionrc ， .versionrc.json或.versionrc.js 。

• 如果您使用的是.versionrc.js則默認導出必須是配置對象，或返回配置對象的函數。

可以通過配置提供由standard-version接受的任何命令行參數。有關可用配置選項的詳細信息，請參考傳統的變成config-spec。

自定義變更生成

默認情況下（截至6.0.0 ）， standard-version使用常規通信預設。

這個預設：

• 緊密粘附於常規commits.org規範。
• 遵循此處維護的配置規範，是高度配置的。
  • 我們已將這些配置設置記錄為向其他工具製造商的建議。

您可以轉動各種錶盤和旋鈕，與ChangElog Generation相關。

例如，假設您使用的是gitlab而不是github，您可以修改以下變量：

• commitUrlFormat ：在提交消息中檢測到的提交SHA的URL格式。
• compareUrlFormat ：用於比較兩個標籤的URL格式。
• issueUrlFormat ：用於鏈接到問題的URL格式。

使這些URL匹配Gitlab的格式，而不是Github的格式。

CLI用法

注意：要將嵌套配置傳遞給CLI而不在package.json中定義它們。 JSON使用DOT符號作為參數eg --skip.changelog 。

第一版

要生成您的ChangElog作為第一個版本，只需做：

 # npm run script
npm run release -- --first-release
# global bin
standard-version --first-release
# npx
npx standard-version --first-release

這將標記發行版，而不會碰撞版本bumpFiles 1 。

準備就緒後，按GIT標籤， npm publish您的第一個版本。 o/

切割釋放

如果通常使用npm version剪切新版本，請這樣做：

 # npm run script
npm run release
# or global bin
standard-version

只要您的git提交消息是常規且準確的，您就不再需要指定SEMVER類型 - 您可以免費獲得ChangElog生成！ o/

剪切版本後，您可以在準備就緒後推動新的Git標籤和npm publish （或npm publish --tag next ）。

發布作為預發行

使用標誌--prerelease生成預釋放：

假設您的代碼的最後一個版本為1.0.0 ，您要投入的代碼已修補更改。跑步：

 # npm run script
npm run release -- --prerelease

這將標記您的版本為： 1.0.1-0 。

如果要命名預釋放，請通過--prerelease <name>指定名稱。

例如，假設您的預訂應包含alpha前綴：

 # npm run script
npm run release -- --prerelease alpha

這將標記為： 1.0.1-alpha.0

毫無疑問將作為目標類型（ npm version - 類）發布

放棄使用自動化版本的使用--release-as與參數major ， minor或patch一樣。

假設您的代碼的最後一個版本是1.0.0 ，您只會降落fix:提交，但是您希望下一個版本成為minor 。只需運行以下內容：

 # npm run script
npm run release -- --release-as minor
# Or
npm run release -- --release-as 1.1.0

您將獲得1.1.0版本，而不是自動生成版本1.0.1 。

注意：您可以組合--release-as和--prerelease酶來生成版本。發布實驗功能時，這很有用。

防止git鉤

如果您使用git掛鉤（例如預先承諾）在提交之前測試代碼，則可以通過傳遞--no-verify選項來防止在提交步驟中驗證鉤子：

 # npm run script
npm run release -- --no-verify
# or global bin
standard-version --no-verify

簽名和標籤

如果您設置了GPG密鑰，請將--sign或-s標誌添加到standard-version命令中。

生命週期腳本

standard-version支持生命週期腳本。這些使您可以在發布期間執行自己的補充命令。以下掛鉤可用並按照記錄的順序執行：

• prerelease ：在任何事情發生之前執行。如果prerelease腳本返回非零退出代碼，則將中止版本控制，但對過程沒有其他影響。
• prebump / postbump ：在版本碰撞之前和之後執行。如果prebump腳本返回版本＃，則將使用它，而不是由standard-version計算的版本。
• prechangelog / postchangelog ：生成更改之前和之後執行。
• precommit / postcommit ：在提交步驟之前和之後打電話。
• pretag / posttag ：在標籤步驟之前和之後打電話。

只需將以下內容添加到您的軟件包。 json即可配置生命週期腳本：

{
  "standard-version" : {
    "scripts" : {
      "prebump" : " echo 9.9.9 "
    }
  }
}

作為一個例子，可以從使用github跟踪您的項目到使用項目JIRA使用postchangelog腳本來替換包含“ https://github.com/” myproject`/issues/'的URL片段，並使用指向JIRA的鏈接 - 假設您已經安裝了替換替換替代品

{
  "standard-version" : {
    "scripts" : {
      "postchangelog" : " replace 'https://github.com/myproject/issues/' 'https://myjira/browse/' CHANGELOG.md "
    }
  }
}

跳過生命週期步驟

您可以changelog bump以下commit添加到您的軟件包：JSON tag

{
  "standard-version" : {
    "skip" : {
      "changelog" : true
    }
  }
}

在發行訂單中犯下產生的工件

如果您想在發布提交中提交生成的工件，則可以使用--commit-all或-a標誌。您將需要上演要犯下的工件，因此您的release命令看起來像這樣：

{
  "standard-version" : {
    "scripts" : {
      "prerelease" : " webpack -p --bail && git add <file(s) to commit> "
    }
  }
}

{
  "scripts" : {
    "release" : " standard-version -a "
  }
}

乾式運行模式

使用標誌運行standard-version --dry-run允許您在不承諾git或更新文件的情況下查看將運行哪些命令。

 # npm run script
npm run release -- --dry-run
# or global bin
standard-version --dry-run

前綴標籤

默認情況下將標籤帶有v如果您想將標籤帶有其他內容，則可以使用-t標誌進行。

standard-version -t @scope/package @

這將使您的標籤前綴看起來像@scope/[email protected]

如果您不想擁有任何標籤前綴，則可以使用-t標誌並為其提供一個空字符串作為值。

注意：簡單地-t或-tag -prefix沒有任何值，將退回到默認的“ V”

CLI幫助

 # npm run script
npm run release -- --help
# or global bin
standard-version --help

代碼用法

 const standardVersion = require ( 'standard-version' )

// Options are the same as command line, except camelCase
// standardVersion returns a Promise
standardVersion ( {
  noVerify : true ,
  infile : 'docs/CHANGELOG.md' ,
  silent : true
} ) . then ( ( ) => {
  // standard-version is done
} ) . catch ( err => {
    console . error ( `standard-version failed with message: ${ err . message } ` )
} )

提示：使用silent選項防止standard-version打印到console 。

常問問題

standard-version與semantic-release有何不同？

semantic-release被描述為：

語義釋放自動化整個軟件包發布工作流程，包括：確定下一個版本號，生成發行說明並發佈軟件包。

儘管兩者都是基於結構化提交消息的相同基礎，但standard-version通過處理版本控制，變更元的生成和git標記採用不同的方法，而無需自動推動（to github）或發布（轉到NPM註冊表）。 standard-version的使用僅影響您的本地git回購 - 它根本不會影響遠程資源。運行standard-version後，您可以查看發布狀態，正確的錯誤並遵循對您的代碼庫最有意義的發布策略。

我們認為它們都是很棒的工具，我們鼓勵人們使用semantic-release而不是standard-version如果它們對他們的用例有意義。

合併PR時，我應該總是擠壓嗎？

合併拉的請求時，壁板提交的說明假設一個PR最多等於一個功能或修復。

如果您有多個功能或修復單個PR中的降落，並且每個提交都會使用結構化消息，則可以在接受PR時進行標準合併。合併後，這將保留您分支機構的提交歷史。

儘管這將允許每個提交作為ChangElog中的單獨條目包括在內，但條目將無法參考拉動更改的PR，因為保留的提交消息不包括PR號。

因此，我們建議將每個PR的範圍保留到一個一般功能或修復中。在實踐中，這使您可以在進行每個小更改時使用非結構化的提交消息，然後將它們擠入一個結構化消息（引用PR編號）後，一旦審查並接受了它們。

我可以將standard-version用於其他元數據文件，語言或版本文件嗎？

從版本7.1.0開始，您可以配置多個bumpFiles和packageFiles 。

1. 指定一個自定義的bumpFile “ filename ”，這是要“ bump”的文件的途徑
2. 指定bumpFile “ updater ”，這就是將文件撞到的方式。一個。如果您使用的是通用類型，則可以通過指定type來使用standard-version的內置updaters之一。 b。如果您使用了一個較不常見的版本文件，則可以創建自己的updater 。

 // .versionrc
{
  "bumpFiles" : [
    {
      "filename" : "MY_VERSION_TRACKER.txt" ,
      // The `plain-text` updater assumes the file contents represents the version.
      "type" : "plain-text"
    } ,
    {
      "filename" : "a/deep/package/dot/json/file/package.json" ,
      // The `json` updater assumes the version is available under a `version` key in the provided JSON document.
      "type" : "json"
    } ,
    {
      "filename" : "VERSION_TRACKER.json" ,
      //  See "Custom `updater`s" for more details.
      "updater" : "standard-version-updater.js"
    }
  ]
}

如果使用.versionrc.js作為您的配置文件，則updater也可以設置為對象，而不是路徑：

 // .versionrc.js
const tracker = {
  filename : 'VERSION_TRACKER.json' ,
  updater : require ( './path/to/custom-version-updater' )
}

module . exports = {
  bumpFiles : [ tracker ] ,
  packageFiles : [ tracker ]
} 

自定義updater

預計updater將是一個JavaScript模塊，至少是兩種方法： readVersion和writeVersion 。

readVersion(contents = string): string

此方法用於從提供的文件內容中讀取版本。

返回值有望是語義版本字符串。

writeVersion(contents = string, version: string): string

此方法用於將版本寫入提供的內容。

返回值將直接寫入提供的文件（覆蓋）。

---

讓我們假設我們的VERSION_TRACKER.json具有以下內容：

{
  "tracker" : {
    "package" : {
      "version" : " 1.0.0 "
    }
  }
}

可接受的standard-version-updater.js是：

 // standard-version-updater.js
const stringifyPackage = require ( 'stringify-package' )
const detectIndent = require ( 'detect-indent' )
const detectNewline = require ( 'detect-newline' )

module . exports . readVersion = function ( contents ) {
  return JSON . parse ( contents ) . tracker . package . version ;
}

module . exports . writeVersion = function ( contents , version ) {
  const json = JSON . parse ( contents )
  let indent = detectIndent ( contents ) . indent
  let newline = detectNewline ( contents )
  json . tracker . package . version = version
  return stringifyPackage ( json , indent , newline )
} 

執照

ISC