การกำหนดเวอร์ชัน เสถียรภาพ การเลิกใช้ และนโยบายการสนับสนุน

ภาพรวมโดยสรุป

ทุกหน้าเอกสารของ NextPDF นำพาฟิลด์ lifecycle ใน front matter ของมัน: stability, since, deprecated_since, replaced_by, version_lifecycle และ eol_date ฟิลด์เหล่านั้นเข้ารหัสสัญญาการสนับสนุนไว้แล้ว หน้านี้ระบุสัญญานั้น ไว้ในที่เดียว เพื่อให้ทีมงานที่ใช้งานจริงอ่าน metadata ของหน้าใดก็ได้และประเมิน ความเสี่ยงของการตรึงเวอร์ชัน

NextPDF ปฏิบัติตาม Semantic Versioning 2.0.0 สำหรับหมายเลข release ของมันและ Conventional Commits 1.0.0 สำหรับการสร้าง changelog service provider interface (contract สาธารณะใน NextPDF\Contracts และ NextPDF\Event) ถูกกำกับด้วยกฎ เดียวกัน ดู กฎเสถียรภาพ SPI สำหรับกลไก tag @stability ต่อ contract หน้านี้เป็นนโยบายที่กว้างกว่าซึ่งกฎ SPI ทำให้ เฉพาะเจาะจง

Semantic versioning สำหรับ NextPDF

เวอร์ชัน release คือ MAJOR.MINOR.PATCH ตำแหน่งที่เปลี่ยนบอกคุณว่าอะไรเปลี่ยนได้ ในโค้ดของคุณ

Increment	มันหมายถึงอะไร	อะไรอาจพัง
Major (3.x → 4.0.0)	อนุญาตการเปลี่ยนแปลงที่ทำลายความเข้ากันได้	contract stable อาจเปลี่ยน signature หรือถูกลบ; สัญลักษณ์ที่เลิกใช้ซึ่งถูกทำเครื่องหมายใน major ก่อนหน้าอาจถูกลบ; พฤติกรรมเริ่มต้นอาจเปลี่ยน
Minor (6.0 → 6.1.0)	การเพิ่มที่เข้ากันได้แบบย้อนหลัง	ไม่มีอะไรสำหรับ contract stable interface เสถียรที่เผยแพร่แล้วได้รับ เมธอดที่จำเป็นใหม่เป็นศูนย์ การเติบโตมาจาก contract/interface ใหม่ เมธอดที่เป็นทางเลือกบนคลาส concrete และตัวเลือก constructor/config ใหม่ที่มีค่าเริ่มต้น contract experimental อาจเปลี่ยนที่นี่ พร้อมประกาศการเลิกใช้ก่อน
Patch (4.0.0 → 3.2.1)	การแก้ bug ที่เข้ากันได้แบบย้อนหลัง	ไม่มีอะไรที่ตั้งใจ พฤติกรรมลู่เข้าหา contract ที่บันทึกไว้

กฎปฏิบัติสำหรับพื้นผิว stable: ข้อจำกัด Composer เช่น ^3.2 ได้รับทุก release minor และ patch ในสาย major เดียวกัน โดยไม่มีการเปลี่ยนแปลงที่ทำลายความเข้ากันได้ การเปลี่ยนแปลงที่ทำลายความเข้ากันได้ลงเฉพาะที่ขอบ major

{
    "require": {
        "nextpdf/core": "^3.2"
    }
}

ตรึงให้แน่นขึ้น (ตัวอย่างเช่น ~3.2.0) เมื่อคุณขึ้นกับ contract experimental เพราะ contract experimental อาจเปลี่ยนใน release minor

ป้ายเสถียรภาพ

ฟิลด์ stability ของหน้า และ tag @stability ใน source ของ contract ดึงมาจาก คำศัพท์เดียวกัน ป้ายระบุความแข็งแกร่งของสัญญาความเข้ากันได้

Label	มันรับประกันอะไร	มันเปลี่ยนที่ไหน
stable	พร้อมใช้งานจริง ปลอดภัยที่จะขึ้นกับมัน ไม่มีการเปลี่ยนแปลงที่ทำลายความเข้ากันได้ใน release minor หรือ patch interface เสถียร (เช่น SPI NextPDF\Contracts) ได้รับเมธอดที่จำเป็นใหม่เป็นศูนย์ใน minor หรือ patch — การเติบโตที่เข้ากันได้แบบย้อนหลังมาถึงบน contract ใหม่ เป็นเมธอดที่เป็นทางเลือกบนคลาส concrete หรือผ่านตัวเลือก constructor/config ที่มีค่าเริ่มต้น	release major เท่านั้น
beta	สมบูรณ์ด้านคุณสมบัติและใช้งานได้ แต่พื้นผิวยังไม่ถูกแช่แข็ง จัดการมันเหมือน experimental สำหรับการตรึง: ห่อหรือตรึงให้แน่น	อาจเปลี่ยนใน release minor พร้อมประกาศการเลิกใช้ก่อน
experimental	ใช้งานได้ แต่ชัดเจนว่ายังไม่ถูกแช่แข็ง NextPDF อาจส่ง implementation ของเอนจินที่ทดสอบแล้วในขณะที่ contract สาธารณะยังเคลื่อนไหว	อาจเปลี่ยนใน release minor พร้อมประกาศการเลิกใช้ก่อน
deprecated	กำหนดการสำหรับการลบ หน้าหรือ contract ระบุตัวแทนและ major ที่มันถูกลบ	ถูกลบใน major ถัดไป ไม่เคยใน minor หรือ patch

contract การสตรีม NextPDF\Contracts\CursorInterface และ NextPDF\Contracts\StreamingWriterInterface เป็นตัวอย่างจริงของพื้นผิว experimental: NextPDF ส่ง implementation ที่สมบูรณ์และทดสอบแล้ว แต่ contract สาธารณะยังอาจเปลี่ยนใน release minor ตรึงให้แน่นหรือห่อ contract เช่นนั้นไว้หลัง adapter ของคุณเองก่อนที่คุณจะขึ้นกับมันในการใช้งานจริง

วงจรการเลิกใช้

การเลิกใช้เป็นเส้นทางสี่ขั้นตอนที่นิยามไว้ มันตั้งชื่อตัวแทนเสมอ และการลบถูกเลื่อน ไปยังขอบ major เสมอ

1. ทำเครื่องหมาย เจ้าของตั้ง @stability deprecated บน contract (หรือ deprecated_since บนหน้า) และบันทึกตัวแทนและ major ที่จะลบ บนหน้า deprecated_since คือเวอร์ชันที่แนะนำการเลิกใช้และ replaced_by คือพาธ ผู้สืบทอด canonical
2. ประกาศ การเลิกใช้ถูกประกาศใน changelog สำหรับ release ที่ทำเครื่องหมายมัน
3. ทับซ้อน พื้นผิวที่เลิกใช้และตัวแทนของมันอยู่ร่วมกันอย่างน้อยหนึ่ง release minor เพื่อให้คุณ migrate ได้โดยไม่มีวันเปลี่ยนแบบฉับพลัน
4. ลบ พื้นผิวถูกลบใน release major ที่ระบุ การลบไม่เคยเกิดใน release minor หรือ patch

ตัวอย่างระดับหน้าที่เดินครบทั้งวงจรแล้ว: สูตร legacy /docs/cookbook/php/sign-pades/ ถูกทำเครื่องหมาย deprecated_since: "3.0.0" พร้อม replaced_by: /docs/cookbook/php/sign-pades-b-b/ อยู่ร่วมกับผู้สืบทอดตลอดช่วงการ ทับซ้อน และต่อมาได้ถูกปลดระวางไปแล้ว — ตอนนี้ URL เดิมตอบกลับด้วยการเปลี่ยนเส้นทาง แบบถาวรไปยังสูตรผู้สืบทอด ดังนั้นลิงก์ที่เขียนอ้างถึงหน้าที่ deprecated จึงยังคง ทำงานได้หลังการลบ

วางแผน migration ทันทีที่พื้นผิวถูกทำเครื่องหมาย deprecated เพราะตัวแทนถูกระบุ เสมอและทั้งสองทับซ้อนกันอย่างน้อยหนึ่ง minor คุณจึงย้ายได้ก่อนที่ major ที่ลบ จะมาถึง

วงจรเวอร์ชันและการสนับสนุนด้านความปลอดภัย

ฟิลด์ version_lifecycle จำแนกว่าสายเวอร์ชันที่บันทึกไว้ถูกดูแลอย่างไร ค่าคือ

version_lifecycle	ความหมาย	ได้รับ
active	สายปัจจุบันภายใต้การพัฒนาที่กระตือรือร้น	คุณสมบัติ การแก้ไข และการแก้ไขด้านความปลอดภัย
lts	สายแบบ long-term-support	การแก้ไขและการแก้ไขด้านความปลอดภัยตลอดช่วงการสนับสนุน
maintenance	ผ่านการพัฒนาที่กระตือรือร้นแล้ว ยังคงดูแลอยู่	การแก้ไขด้านความปลอดภัยและการแก้ไข bug ร้ายแรง
frozen	ไม่มีการเปลี่ยนแปลงเชิงฟังก์ชันเพิ่มเติมที่วางแผนไว้	การแก้ไขด้านความปลอดภัยเท่านั้น ที่ใดเหมาะสม
eol	สิ้นสุดอายุการใช้งาน	ไม่มีอะไร ต้องอัปเกรด

เมื่อสายถึงสิ้นสุดอายุการใช้งาน eol_date ของมันบันทึกวันที่ (ISO 8601, YYYY-MM-DD) หน้าที่มี version_lifecycle: eol และ eol_date ที่ผ่านมาแล้ว เป็นสัญญาณให้ migrate ออกจากสายนั้น: มันไม่ได้รับการแก้ไขอีกต่อไป รวมถึงการแก้ไข ด้านความปลอดภัย

นี่คือข้อความนโยบาย ไม่ใช่คำสัญญาตามปฏิทิน ฟิลด์บอกคุณถึง ระดับ ของการสนับสนุน ที่สายอยู่ ปรึกษา changelog และ release note สำหรับเวอร์ชันที่เป็นรูปธรรมที่นำพา การแก้ไขที่กำหนด การแก้ไขด้านความปลอดภัยถูก backport ไปยังสายที่ lifecycle ยังคง รวมมัน (active, lts และ maintenance) ไม่ใช่ไปยังสายที่ทำเครื่องหมาย frozen-โดยไม่มีความเกี่ยวข้อง หรือ eol

ช่วงการสนับสนุนเวอร์ชัน PHP

NextPDF Core ต้องการ PHP >=8.4 <9.0 ช่วงนั้นถูกประกาศใน composer.json ของ เอนจินและเป็นแหล่งความจริงเดียว แพ็กเกจ premium (nextpdf/pro, nextpdf/enterprise) ต้องการช่วงเดียวกัน

• ขอบล่าง (>=8.4) คือ runtime ขั้นต่ำ การยกมันขึ้นเป็นการเปลี่ยนแปลงที่ ทำลายความเข้ากันได้และลงเฉพาะที่ขอบ major
• ขอบบน (<9.0) ไม่รวม PHP major ถัดไปจนกว่ามันจะถูกตรวจสอบความถูกต้อง การรองรับ PHP major ใหม่ถูกเพิ่มใน release ของ NextPDF ไม่ใช่สมมติ

หน้าเอกสารยังนำพารายการ compatibility ของเวอร์ชัน PHP minor ที่สูตรถูกตรวจสอบ เทียบกับ หน้าอาจระบุ minor ที่เก่ากว่า (ตัวอย่างเช่น ["8.1", "8.2", "8.3", "8.4"]) ที่สูตรพกพาได้ ในขณะที่พื้นการติดตั้งที่เข้มงวด ของเอนจินยังคงเป็น >=8.4 เมื่อสงสัย ข้อจำกัด composer.json ชนะ hint compatibility ของหน้า

วิธีอ่าน front matter lifecycle ของหน้า

ใช้หกฟิลด์เหล่านี้เพื่อประเมินหน้าใดก็ตามก่อนที่คุณจะสร้างบนมัน

Field	Type	วิธีอ่านมัน
stability	stable | beta | experimental | deprecated	สัญญาความเข้ากันได้สำหรับพื้นผิวที่หน้าบันทึก
since	SemVer (เช่น "3.1.0")	เวอร์ชันที่แนะนำพื้นผิวที่บันทึก การติดตั้งของคุณต้องอย่างน้อยเวอร์ชันนี้
deprecated_since	SemVer หรือว่าง	หากตั้งไว้ พื้นผิวถูกเลิกใช้ ค่าคือเวอร์ชันที่เลิกใช้มัน ว่างหมายถึงไม่ถูกเลิกใช้
replaced_by	พาธของไซต์หรือว่าง	เมื่อเลิกใช้ หน้าผู้สืบทอด canonical ที่จะ migrate ไป
version_lifecycle	active | lts | maintenance | frozen | eol	ระดับการดูแลของสายที่บันทึก
eol_date	วันที่ ISO หรือว่าง	เมื่อ version_lifecycle เป็น eol คือวันสิ้นสุดอายุการใช้งาน ว่างในกรณีอื่น

ตัวอย่างการอ่านที่ลงมือทำ: หน้าที่มี stability: stable, since: "3.0.0", deprecated_since: "" และ version_lifecycle: active บันทึกพื้นผิวที่พร้อม ใช้งานจริงซึ่งมีอยู่ตั้งแต่ 3.0.0 ไม่ถูกเลิกใช้ และอยู่บนสายที่ดูแลอย่างกระตือรือร้น คุณสามารถขึ้นกับมันภายใต้ข้อจำกัด major แบบ ^ หน้าที่มี stability: deprecated และ replaced_by ที่ไม่ว่างเป็นสัญญาณ migration: อ่านหน้าผู้สืบทอดและวางแผน การย้ายก่อน major ถัดไป

ความสอดคล้องตามมาตรฐาน

นโยบายนี้สอดคล้องกับ Semantic Versioning 2.0.0 สำหรับการกำหนดหมายเลขเวอร์ชันและ Conventional Commits 1.0.0 สำหรับการสร้าง changelog ช่วงการสนับสนุน PHP คือ ข้อจำกัด >=8.4 <9.0 ที่ประกาศใน composer.json ของเอนจิน หน้านี้ไม่อ้างเรื่อง มาตรฐานเชิงบรรทัดฐานใดๆ ด้วยตัวเอง มันบันทึกสัญญาการสนับสนุนที่ฟิลด์ front-matter lifecycle เข้ารหัสไว้แล้ว

ดูเพิ่มเติม

• กฎเสถียรภาพ SPI — tag @stability ต่อ contract และสี่ระดับของคำสัญญาความเข้ากันได้แบบย้อนหลัง (interface, enum, frozen value-object, experimental)
• เมทริกซ์สถานะการรองรับ CSS — สถานะ การรองรับต่อโมดูลที่ตรวจสอบความจริงสำหรับไปป์ไลน์การเรนเดอร์ HTML และ CSS
• ดัชนีเอกสารอ้างอิง — จุดเข้าสำหรับเอกสารอ้างอิง API การกำหนดค่า และความเข้ากันได้