standard version

เวอร์ชันมาตรฐาน

standard-version เลิกใช้แล้ว หากคุณเป็นผู้ใช้ GitHub ฉันขอแนะนำให้ปล่อยตัวเป็นทางเลือกอื่น หากคุณไม่สามารถใช้การกระทำของ GitHub ได้หรือหากคุณต้องการที่จะยึดติดกับ standard-version ด้วยเหตุผลอื่น ๆ คุณสามารถใช้ส้อมที่ส่งมอบและแท็กของ standard-version

ยูทิลิตี้สำหรับการกำหนดเวอร์ชันโดยใช้ Semver และ Changelog Generation ขับเคลื่อนโดย Commental Commits

มีปัญหา? ต้องการมีส่วนร่วม? เข้าร่วมกับเราในการหย่อนของชุมชนโหนด

มันทำงานอย่างไร:

1. ทำตามข้อกำหนดทั่วไปในที่เก็บข้อมูลของคุณ
2. เมื่อคุณพร้อมที่จะเปิดตัวให้เรียกใช้ standard-version

standard-version จะทำสิ่งต่อไปนี้:

1. ดึงเวอร์ชันปัจจุบันของที่เก็บข้อมูลของคุณโดยดูที่ packageFiles [1] ล้มกลับไปที่ git tag สุดท้าย
2. bump เวอร์ชันใน bumpFiles [1] ขึ้นอยู่กับการกระทำของคุณ
3. สร้าง changelog ตามการกระทำของคุณ (ใช้ changelog ทั่วไปภายใต้ประทุน)
4. สร้าง commit ใหม่รวมถึง bumpFiles ของคุณ [1] และการเปลี่ยนแปลงที่อัปเดต
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

สิ่งนี้มีประโยชน์ในการทำให้ repo/package ของคุณพกพามากขึ้นเพื่อให้นักพัฒนารายอื่นสามารถลดรุ่นได้โดยไม่ต้องติดตั้ง standard-version ทั่วโลกบนเครื่องของพวกเขา

เป็น bin ทั่วโลก

ติดตั้งทั่วโลก (เพิ่มไปยัง PATH ของคุณ):

 npm i -g standard-version

ตอนนี้คุณสามารถใช้ standard-version แทน npm version

สิ่งนี้มีประโยชน์ในการอนุญาตให้คุณใช้ standard-version ใน repo/package ใด ๆ โดยไม่ต้องเพิ่มการพึ่งพา dev ให้กับแต่ละคน

ใช้ npx

ณ [email protected] , npx ถูกติดตั้งควบคู่ไปกับ npm การใช้ npx คุณสามารถใช้ standard-version ได้โดยไม่ต้องเก็บไฟล์ package.json โดยการรัน: npx standard-version

วิธีนี้มีประโยชน์อย่างยิ่งเมื่อใช้ standard-version ในโครงการที่ไม่ใช่ JavaScript

การกำหนดค่า

คุณสามารถกำหนดค่า standard-version ได้โดย:

1. การวางสแตนซ่า standard-version ใน package.json ของคุณ json (สมมติว่าโครงการของคุณคือ JavaScript)
2. การสร้าง .versionrc , .versionrc.json หรือ .versionrc.js

• หากคุณใช้ .versionrc.js การส่งออกเริ่มต้นของคุณจะต้องเป็นวัตถุการกำหนดค่าหรือฟังก์ชั่นที่ส่งคืนวัตถุการกำหนดค่า

พารามิเตอร์บรรทัดคำสั่งใด ๆ ที่ได้รับการยอมรับจาก standard-version สามารถให้บริการแทนการกำหนดค่า โปรดดูที่ changelog-config-spec ทั่วไปสำหรับรายละเอียดเกี่ยวกับตัวเลือกการกำหนดค่าที่มีอยู่

ปรับแต่งการสร้าง Changelog

โดยค่าเริ่มต้น (ณ 6.0.0 ) standard-version ใช้การตั้งค่าการประชุมที่ตั้งไว้ล่วงหน้า

ที่ตั้งไว้ล่วงหน้านี้:

• ปฏิบัติตามข้อกำหนดของ Conventionalcommits.org อย่างใกล้ชิด
• สามารถกำหนดค่าได้สูงตามข้อกำหนดการกำหนดค่าที่เก็บรักษาไว้ที่นี่
  • เราได้จัดทำเอกสารการตั้งค่าการกำหนดค่าเหล่านี้เป็นคำแนะนำสำหรับผู้ผลิตเครื่องมืออื่น ๆ

มีปุ่มหมุนและลูกบิดที่หลากหลายที่คุณสามารถเปลี่ยนเกี่ยวข้องกับการสร้าง Changelog

ตัวอย่างเช่นสมมติว่าคุณกำลังใช้ gitlab มากกว่า gitHub คุณอาจแก้ไขตัวแปรต่อไปนี้:

• commitUrlFormat : รูปแบบ URL ของ commit shas ที่ตรวจพบในข้อความ commit
• compareUrlFormat : รูปแบบ URL ที่ใช้เพื่อเปรียบเทียบสองแท็ก
• issueUrlFormat : รูปแบบ URL ที่ใช้ในการเชื่อมโยงไปยังปัญหา

การทำให้ URL เหล่านี้ตรงกับรูปแบบของ Gitlab มากกว่าของ GitHub

การใช้งาน CLI

หมายเหตุ: หากต้องการผ่านการกำหนดค่าที่ซ้อนกันไปยัง CLI โดยไม่ต้องกำหนดไว้ใน package.json ใช้สัญลักษณ์ dot เป็นพารามิเตอร์ eg --skip.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 อีกต่อไป - และคุณจะได้รับการเปลี่ยนแปลงอย่างฟรี! o/

หลังจากที่คุณตัดการเปิดตัวคุณสามารถผลักดัน GIT TAG ใหม่และ 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

หากคุณใช้ hook git เช่น pre-commit เพื่อทดสอบรหัสของคุณก่อนที่จะกระทำคุณสามารถป้องกันไม่ให้ตะขอได้รับการตรวจสอบในระหว่างขั้นตอนการกระทำโดยผ่านตัวเลือก --no-verify :

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

การเซ็นสัญญาและแท็ก

หากคุณมีการตั้งค่าคีย์ GPG ให้เพิ่ม --sign หรือ -s FLAG ลงในคำสั่ง standard-version ของคุณ

สคริปต์วงจรชีวิต

standard-version รองรับสคริปต์วงจรชีวิต สิ่งเหล่านี้ช่วยให้คุณสามารถดำเนินการคำสั่งเสริมของคุณเองในระหว่างการเปิดตัว ตะขอต่อไปนี้พร้อมใช้งานและดำเนินการในการสั่งซื้อเอกสาร:

• prerelease : ดำเนินการก่อนที่จะเกิดอะไรขึ้น หากสคริปต์ prerelease ส่งคืนรหัสออกที่ไม่ใช่ศูนย์การกำหนดเวอร์ชันจะถูกยกเลิก แต่จะไม่มีผลกระทบอื่น ๆ ต่อกระบวนการ
• prebump / postbump : ดำเนินการก่อนและหลังเวอร์ชันถูกกระแทก หากสคริปต์ prebump ส่งคืนเวอร์ชัน #มันจะถูกใช้มากกว่าเวอร์ชันที่คำนวณโดย standard-version
• prechangelog / postchangelog : ดำเนินการก่อนและหลังการเปลี่ยนแปลงถูกสร้างขึ้น
• precommit / postcommit : เรียกก่อนและหลังขั้นตอนการกระทำ
• pretag / posttag : เรียกก่อนและหลังขั้นตอนการติดแท็ก

เพียงเพิ่มสิ่งต่อไปนี้ลงใน package.json ของคุณเพื่อกำหนดค่าสคริปต์ Lifecycle:

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

เป็นตัวอย่างในการเปลี่ยนจากการใช้ GitHub เพื่อติดตามรายการของคุณเพื่อใช้โครงการของคุณ JIRA ใช้สคริปต์ postchangelog เพื่อแทนที่ส่วน URL ที่มี 'https://github.com/`myproject`/issues/' พร้อมลิงก์ไปยังจิราของคุณ

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

ข้ามขั้นตอนวงจรชีวิต

คุณสามารถข้ามขั้นตอนชีวิตใด ๆ ( bump , changelog , commit , tag ) โดยเพิ่มสิ่งต่อไปนี้ลงใน package.json:

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

การสร้างสิ่งประดิษฐ์ที่สร้างขึ้นในการเปิดตัว

หากคุณต้องการที่จะสร้างสิ่งประดิษฐ์ที่สร้างขึ้นในการเปิดตัวการเปิดตัวคุณสามารถใช้ --commit-all หรือ -a flag คุณจะต้องจัดทำสิ่งประดิษฐ์ที่คุณต้องการให้เกิดขึ้นดังนั้นคำสั่ง 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 ให้คุณ โดยไม่ต้อง กดอัตโนมัติ (ไปยัง GitHub) หรือการเผยแพร่ (ไปยังรีจิสทรี NPM) การใช้ standard-version จะส่งผลกระทบต่อการซื้อสินค้า GIT ในพื้นที่ของคุณเท่านั้น - มันไม่ส่งผลกระทบต่อทรัพยากรระยะไกลเลย หลังจากที่คุณเรียกใช้ standard-version คุณสามารถตรวจสอบสถานะการวางจำหน่ายของคุณแก้ไขข้อผิดพลาดและทำตามกลยุทธ์การวางจำหน่ายที่เหมาะสมที่สุดสำหรับ codebase ของคุณ

เราคิดว่าพวกเขาเป็นทั้งเครื่องมือที่ยอดเยี่ยมและเราขอแนะนำให้ผู้คนใช้ semantic-release แทนที่จะเป็น standard-version ถ้ามันเหมาะสมสำหรับกรณีการใช้งานของพวกเขา

ฉันควรทำสควอชเสมอเมื่อรวม PRS หรือไม่?

คำแนะนำในการทำสควอชกระทำเมื่อรวมคำขอดึงจะถือว่า หนึ่ง PR เท่ากับส่วนใหญ่หนึ่งคุณลักษณะหรือการแก้ไข

หากคุณมีคุณสมบัติหลายอย่างหรือแก้ไขการเชื่อมโยงไปถึงใน PR เดียวและแต่ละครั้งที่กระทำจะใช้ข้อความที่มีโครงสร้างคุณสามารถทำการรวมมาตรฐานเมื่อยอมรับการประชาสัมพันธ์ สิ่งนี้จะรักษาประวัติศาสตร์การกระทำจากสาขาของคุณหลังจากการผสาน

แม้ว่าสิ่งนี้จะช่วยให้แต่ละที่เกี่ยวข้องจะรวมเป็นรายการแยกต่างหากในการเปลี่ยนแปลงของคุณรายการจะ ไม่ สามารถอ้างอิง PR ที่ดึงการเปลี่ยนแปลงเนื่องจากข้อความการกระทำที่เก็บรักษาไว้ไม่รวมหมายเลข PR

ด้วยเหตุนี้เราขอแนะนำให้รักษาขอบเขตของการประชาสัมพันธ์แต่ละครั้งให้เป็นหนึ่งในคุณสมบัติทั่วไปหรือการแก้ไข ในทางปฏิบัติสิ่งนี้จะช่วยให้คุณใช้ข้อความที่ไม่มีโครงสร้างเมื่อทำการเปลี่ยนแปลงเล็กน้อยแต่ละครั้งแล้วบีบให้พวกเขาลงในการกระทำเดียวกับข้อความที่มีโครงสร้าง (อ้างอิงหมายเลขประชาสัมพันธ์) เมื่อพวกเขาได้รับการตรวจสอบและยอมรับแล้ว

ฉันสามารถใช้ standard-version สำหรับไฟล์เมตาดาต้าเพิ่มเติมไฟล์หรือไฟล์เวอร์ชันได้หรือไม่?

ตั้งแต่เวอร์ชัน 7.1.0 คุณสามารถกำหนดค่า bumpFiles และ packageFiles ได้หลายตัว

1. ระบุ " filename " bumpFile ที่กำหนดเองนี่คือเส้นทางไปยังไฟล์ที่คุณต้องการ "Bump"
2. ระบุ " updater " bumpFile นี่คือ วิธีที่ ไฟล์จะถูกกระแทก . หากคุณใช้ประเภททั่วไปคุณสามารถใช้หนึ่งใน updaters ในตัวของ standard-version ได้โดยการระบุ type ข. หากคุณใช้ไฟล์รุ่นที่น้อยกว่าคุณสามารถสร้าง 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