ข้อกำหนดสำหรับ Changelog

ข้อกำหนดสำหรับ Changelog

หน้านี้กำหนดข้อตกลงที่รีโพ NextPDF สาธารณะทุกรายการต้องปฏิบัติตามเมื่อบันทึกการเปลี่ยนแปลงและเผยแพร่รีลีส เอกสารนี้เป็นข้อมูลอ้างอิงด้านข้อกำหนด ไม่ได้กำหนดพฤติกรรมของแพ็กเกจ บันทึกรีลีสแยกตามแพ็กเกจและเวอร์ชันอยู่ใน CHANGELOG.md ของแต่ละรีโพ กฎร่วมเหล่านี้ช่วยให้บทสรุป changelog ข้ามรีโพ สอดคล้องกันและปลอดจากการรั่วไหลของข้อมูล

Conventional Commits 1.0.0

หัวข้อ commit ทุกรายการใช้รูปแบบ type(scope): description โดย type เป็นค่าใดค่าหนึ่งต่อไปนี้:

ประเภท	ความหมาย	ผู้ใช้มองเห็น	ผลต่อเวอร์ชัน
feat	ความสามารถใหม่	ใช่	เพิ่ม minor
fix	แก้ไขพฤติกรรมที่ไม่ถูกต้อง	ใช่	เพิ่ม patch
perf	ปรับปรุงประสิทธิภาพโดยไม่เปลี่ยนพฤติกรรม	ใช่	เพิ่ม patch
refactor	ปรับโครงสร้างภายในโดยไม่มีการเปลี่ยนแปลงที่สังเกตได้	ไม่	ไม่มี
docs	เฉพาะเอกสารเท่านั้น	ไม่	ไม่มี
test	เฉพาะการทดสอบเท่านั้น	ไม่	ไม่มี
build / ci	เฉพาะ build หรือ pipeline เท่านั้น	ไม่	ไม่มี
chore	งานบำรุงรักษา การพึ่งพา หรือเครื่องมือ	ไม่	ไม่มี
revert	ย้อนกลับ commit ก่อนหน้า	ขึ้นอยู่กับกรณี	ขึ้นอยู่กับกรณี

การเปลี่ยนแปลงที่ทำให้เข้ากันไม่ได้ต้องระบุด้วย ! หลังประเภทหรือ scope (feat(api)!: …) หรือใช้ footer BREAKING CHANGE: การระบุแบบใดแบบหนึ่งจะเพิ่มเวอร์ชัน major ตาม Semantic Versioning ให้บันทึกการแก้ไขที่เกี่ยวข้องกับความปลอดภัย เพื่อให้ปรากฏในคอลัมน์ Security ของบทสรุปข้ามรีโพได้

Semantic Versioning 2.0.0

การเพิ่มหมายเลขเวอร์ชันเป็นไปตามกฎที่กำหนดไว้ตายตัว รีลีสที่มีการเปลี่ยนแปลงที่ทำให้เข้ากันไม่ได้อย่างน้อยหนึ่งรายการจัดเป็น major หากไม่ใช่กรณีนั้น รีลีสที่มี feat อย่างน้อยหนึ่งรายการจัดเป็น minor หากยังไม่ใช่กรณีนั้น รีลีสที่มี fix หรือ perf อย่างน้อยหนึ่งรายการจัดเป็น patch แพ็กเกจก่อน 1.0 อาจเพิ่ม minor สำหรับการเปลี่ยนแปลงที่ทำให้เข้ากันไม่ได้ตาม SemVer §4 commit ยังคงต้องมีเครื่องหมายการเปลี่ยนแปลงที่ทำให้เข้ากันไม่ได้ เพื่อให้บทสรุปยังคงถูกต้อง

การจัดกลุ่มแบบ Keep a Changelog

ไฟล์ CHANGELOG.md ของแต่ละรีโพปฏิบัติตาม Keep a Changelog 1.1.0: จัดกลุ่มรายการต่างๆตามเวอร์ชันที่รีลีสแล้วภายใต้ Added, Changed, Deprecated, Removed, Fixed และ Security ส่วน [Unreleased] สามารถเก็บบันทึกงานที่กำลังดำเนินการในรีโพได้ แต่ บทสรุปข้ามรีโพ จะนับเฉพาะเวอร์ชันที่ มีแท็กและรีลีสแล้ว เท่านั้น งานที่ยังไม่ได้รีลีสจะไม่ปรากฏในดัชนีสาธารณะ

วิธีได้มาซึ่งบทสรุปข้ามรีโพ (และวิธีรักษาให้ปลอดจากการรั่วไหลของข้อมูล)

ตารางบทสรุปใน ดัชนี changelog สร้างจากการอ่านประวัติ Conventional Commits ของแต่ละรีโพที่แท็กรีลีสล่าสุด โดยเป็นการอ่านแบบอ่านอย่างเดียว แล้วนับจำนวนตามหมวดหมู่ กฎการได้มาถูกกำหนดขอบเขตไว้อย่างจงใจให้แคบ เพื่อไม่ให้รายละเอียดภายในรั่วไหลออกไป:

1. จำนวน ไม่ใช่เนื้อหา รายงานเฉพาะ จำนวน commit ในแต่ละประเภทที่ผู้ใช้มองเห็นเท่านั้น ไม่แสดงหัวข้อ เนื้อหา footer หรือ hash ของ commit
2. เฉพาะประเภทที่ผู้ใช้มองเห็นเท่านั้น docs, test, ci, chore และ refactor ถูกแยกออก เพราะไม่ได้เปลี่ยนแปลงสิ่งใดที่ผู้ใช้แพ็กเกจสังเกตเห็น
3. เฉพาะที่รีลีสแล้วเท่านั้น จะนับ commit ก็ต่อเมื่อ commit นั้นกลายเป็นส่วนหนึ่งของรีลีสที่มีแท็กของแพ็กเกจสาธารณะแล้วเท่านั้น
4. ไม่มีตัวระบุ จะไม่เปิดเผยการอ้างอิงถึง issue ticket cycle wave หรือ work-item ภายในที่อาจปรากฏใน scope ของ commit ส่วนตัว เพราะจะไม่แสดงข้อความของ scope เอง ระบบอ่านเฉพาะประเภทเท่านั้น
5. ไม่มีการระบุที่มาของระบบอัตโนมัติ จะไม่อ่านหรือแสดง trailer ของระบบอัตโนมัติที่ใช้สร้างผลงาน

ดังนั้น changelog สาธารณะจึงเป็นบทสรุปตามหมวดหมู่พร้อมลิงก์ไปยัง CHANGELOG.md ของแต่ละแพ็กเกจ ไม่ใช่ฟีด commit แบบรวม บทสรุปนี้ปลอดจากการรั่วไหลของข้อมูลภายในโดยการออกแบบ ส่วนเนื้อความรีลีสที่ถือเป็นข้อมูลทางการยังคงอยู่กับแพ็กเกจเจ้าของ

ดูเพิ่มเติม

• Changelog ข้ามรีโพ
• ข้อกำหนดสำหรับสูตรการผสานการทำงาน
• Conventional Commits 1.0.0
• Semantic Versioning 2.0.0