กลยุทธ์เวอร์ชัน Qiskit SDK
หมายเลขเวอร์ชัน Qiskit ปฏิบัติตาม Semantic Versioning
หมายเลขเวอร์ชันประกอบด้วยสามส่วนหลัก: เวอร์ชัน major, minor และ
patch ตัวอย่างเช่น ในหมายเลขเวอร์ชัน X.Y.Z, X คือเวอร์ชัน major,
Y คือเวอร์ชัน minor และ Z คือเวอร์ชัน patch
การเปลี่ยนแปลง API ที่ทำให้ใช้ไม่ได้กับของเดิมสงวนไว้สำหรับการ release เวอร์ชัน major ระยะเวลา ขั้นต่ำ ระหว่างการ release major version คือหนึ่งปี Minor versions เพิ่ม ฟีเจอร์ใหม่และแก้ไขบั๊กโดยไม่ทำลายความเข้ากันได้ของ API และ เผยแพร่เป็นระยะ (ปัจจุบันทุกสามเดือน) สำหรับ เฉพาะ major version ปัจจุบัน Patch versions ให้การแก้ไขบั๊กที่พบใน minor version ล่าสุดของแต่ละ release series ที่ยังรองรับอยู่ (นั่นคือ major version) เรารองรับ release series ได้สูงสุดสองชุดในคราวเดียว ซึ่งเกิดขึ้น เฉพาะช่วงที่ทับซ้อนกันหลังจาก release major version ใหม่ ดังที่อธิบายโดยละเอียดด้านล่าง
ตารางเวลาการ release
ตารางเวลาการ release โดยประมาณแสดงไว้ด้านล่าง:
สำหรับตารางเวลาการ release ที่เป็นปัจจุบัน ดูที่ รายการ milestones ของ Qiskit GitHub project ซึ่งจะมีแผน release ปัจจุบันเสมอ
เมื่อ release major version ใหม่, major version ก่อนหน้าจะได้รับการสนับสนุน อย่างน้อยหกเดือนด้วยการแก้ไขบั๊กเท่านั้น และหนึ่งปีสำหรับการแก้ไขความปลอดภัย ในช่วงเวลานี้ มีการเผยแพร่เฉพาะ patch releases สำหรับ major version นี้ patch version สุดท้ายจะเผยแพร่เมื่อสิ้นสุดการสนับสนุน และ release นั้น ยังบันทึกการสิ้นสุดการสนับสนุนสำหรับ major version series นั้นด้วย จำเป็นต้องมีช่วงเวลา สนับสนุนที่ยาวนานกว่าสำหรับ major version ก่อนหน้า เพื่อให้ผู้ใช้งาน Qiskit downstream และผู้ใช้ของพวกเขามีโอกาสย้ายโค้ด libraries downstream ที่ พึ่งพา Qiskit ไม่ควรยกระดับ minimum required Qiskit version เป็น major version ใหม่ทันทีหลัง release เพราะ user base ของ library ต้องการเวลา เพื่อย้ายไปใช้การเปลี่ยนแปลง API ใหม่ การมีช่วงเวลาสนับสนุนที่ขยายออก สำหรับ Qiskit major version ก่อนหน้าให้เวลาโปรเจกต์ downstream เพื่อให้แน่ใจว่า เข้ากันได้กับ major version ถัดไป โปรเจกต์ downstream สามารถรองรับ release series สองชุดในคราวเดียวเพื่อให้ผู้ใช้มีเส้นทางในการย้าย
สำหรับ semantic versioning, Qiskit public API คือ
module, class, function หรือ method ที่มีเอกสารซึ่งไม่ถูกทำเครื่องหมายว่าเป็น private
(ด้วยคำนำหน้าขีดล่าง _) อย่างไรก็ตาม อาจมีข้อยกเว้นชัดเจนสำหรับ
API เฉพาะบางอย่าง ในกรณีดังกล่าว API เหล่านี้จะบันทึกอย่างชัดเจน
ว่ายังไม่ถือว่าเป็น stable interfaces และจะมีการแสดงคำเตือนที่ผู้ใช้มองเห็น
อยู่เสมอเมื่อใช้งาน unstable interfaces เหล่านี้ นอกจากนี้ ในบางกรณี
interface ที่ถูกทำเครื่องหมายว่า private ถือเป็นส่วนหนึ่งของ public
API โดยทั่วไปเกิดขึ้นในสองกรณีเท่านั้น: ทั้งการกำหนด abstract interface
ที่ subclasses ตั้งใจจะ override/implement private method
เป็นส่วนหนึ่งของการกำหนด implementation ของ interface, หรือเมธอด
low-level สำหรับการใช้งานขั้นสูงที่มี stable interfaces แต่ไม่ถือว่าปลอดภัยสำหรับใช้งาน
เพราะผู้ใช้ต้องรับผิดชอบ class/safety invariants เอง
(ตัวอย่าง canonical คือเมธอด QuantumCircuit._append)
Python versions ที่รองรับ, minimum supported Rust version (สำหรับ build Qiskit จาก source) และ Python package dependencies ใด ๆ (รวมถึง minimum supported versions ของ dependencies) ที่ Qiskit ใช้ไม่ได้เป็นส่วนหนึ่งของ การรับประกันความเข้ากันได้แบบย้อนหลังและอาจเปลี่ยนแปลงในทุก release เฉพาะ minor หรือ major version releases เท่านั้นที่จะยกระดับ minimum requirements สำหรับการใช้หรือ build Qiskit (รวมถึงการเพิ่ม dependencies ใหม่) แต่ patch fixes อาจรวมการสนับสนุน Python versions ใหม่หรือ dependencies อื่น ๆ โดยปกติ minimum version ของ dependency จะเพิ่มขึ้นเมื่อ dependency versions เก่าไม่ได้รับการสนับสนุนแล้ว หรือ เมื่อไม่สามารถรักษาความเข้ากันได้กับ release ล่าสุดของ dependency และ version เก่า
กลยุทธ์การอัปเกรด
เมื่อ release major version ใหม่ เส้นทางการอัปเกรดที่แนะนำ
คือก่อนอื่นอัปเกรดเป็น minor version ล่าสุดบน major version ก่อนหน้า
ไม่นานก่อน major version ใหม่ จะมีการเผยแพร่ final minor version
final minor version release X.Y+1.0.0 นี้เทียบเท่ากับ
X.Y.0 แต่มีคำเตือนและ deprecations สำหรับการเปลี่ยนแปลง API ที่เกิดขึ้น
บน major version series ใหม่
ตัวอย่างเช่น ก่อน release 1.0.0 ทันที จะมีการเผยแพร่ release 0.46.0 Release 0.46.0 จะเทียบเท่ากับ release 0.45.0 แต่มี deprecation warnings เพิ่มเติมที่บันทึกการเปลี่ยนแปลง API ที่เกิดขึ้น เป็นส่วนหนึ่งของ release 1.0.0 รูปแบบนี้จะใช้สำหรับ major version releases ในอนาคต
ผู้ใช้ Qiskit ควรอัปเกรดเป็น final minor version นี้ก่อน
เพื่อดู deprecation warnings และปรับการใช้งาน Qiskit
ก่อนลองใช้ release ที่อาจมีการเปลี่ยนแปลง major version ก่อนหน้า
จะไ ด้รับการสนับสนุนอย่างน้อยหกเดือนเพื่อให้เวลาอัปเกรดเพียงพอ รูปแบบทั่วไปในการจัดการนี้คือการ pin maximum version เพื่อ
หลีกเลี่ยงการใช้ major release series ถัดไปจนกว่าจะมั่นใจว่าเข้ากันได้
ตัวอย่างเช่น การระบุ qiskit<2 ในไฟล์ requirements เมื่อ Qiskit major version ปัจจุบันคือ 1 ทำให้มั่นใจว่า
คุณใช้ Qiskit version ที่ไม่มีการเปลี่ยนแปลง API ที่ทำให้ใช้ไม่ได้
การ cap version ให้น้อยกว่า major version ถัดไป
ทำให้มั่นใจว่าคุณเห็น deprecation warnings ก่อน
major version release
หากไม่มี cap, pip ติดตั้ง
version ล่าสุดที่มีอยู่ตามค่าเริ่มต้น
รูปแบบการ serialize QPY เข้ากันได้แบบย้อนหลัง เพื่อให้ Qiskit release ใหม่สามารถโหลดไฟล์ QPY
ที่สร้างด้วย Qiskit release เก่าได้เสมอ อย่างไรก็ตาม รูปแบบไม่ได้เข้ากันได้แบบไปข้างหน้า ดังนั้นในหลักการแล้ว ไม่สามารถ
โหลดไฟล์ QPY ที่สร้างด้วย Qiskit version ใหม่โดยใช้ release เก่าได้ เพื่ออำนวยความสะดวกในการย้ายผู้ใช้ข้าม major version releases, ฟังก์ชัน qiskit.qpy.dump() จะรองรับ overlapping version อย่างน้อยหนึ่งชุดระหว่าง release X.0.0 และ X-1.Y.0 เสมอ (โดยที่ Y คือ minor version สุดท้ายของ
series นั้น) พารามิเตอร์ qiskit.qpy.dump(..., version=...) จะเปิดใช้การบันทึกไฟล์ QPY format ที่โหลดได้จาก major version ทั้งคู่จาก release ที่ใหม่กว่า
ดูรายละเอียดเพิ่มเติมใน RFC 0020
Pre-releases
สำหรับ minor และ major version release แต่ละครั้ง Qiskit เผยแพร่ pre-releases ที่
เข้ากันได้กับ PEP440 โดยทั่วไป
เหล่านี้คือ release candidates ในรูปแบบ X.Y.0rc1 release rc
จะมี API surface ที่ finalized แล้วและใช้สำหรับทดสอบ release ที่วางแผนไว้
โปรดทราบว่าเมื่อเผยแพร่ PEP440 pre-release suffixes (เช่น a, b หรือ pre)
จะไ ม่มีการรับประกันเหมือนกับ rc release และเป็นเพียง
preview release เท่านั้น API อาจเปลี่ยนแปลงระหว่าง pre-releases เหล่านี้
และ final release ที่มีหมายเลขเวอร์ชันนั้น ตัวอย่างเช่น 1.0.0pre1 อาจมี
final API ที่แตกต่างจาก 1.0.0
Post-releases
หากมีปัญหากับ packaging ของ release อาจมีการออก post-release
เพื่อแก้ไข เหล่านี้จะอยู่ในรูปแบบ X.Y.Z.1 โดยที่เลขที่สี่
ระบุว่าเป็น post-release แรกของ release X.Y.Z
ตัวอย่างเช่น qiskit-terra (ชื่อ package เดิมของ Qiskit) release 0.25.2
มีปัญหาบางอย่างกับการเผยแพร่ sdist package และมีการเผยแพร่ post-release
0.25.2.1 ที่แก้ไขปัญหานั้น โค้ดเหมือนกันทุกประการ และ
0.25.2.1 แก้ไขเพียงปัญหา packaging ของ release เท่านั้น
วิธีที่ผู้มีส่วนร่วมสามารถทำเครื่องหมาย deprecations
ดู deprecation guide ใน Qiskit SDK repository สำหรับคำแนะนำในการเพิ่ม deprecations ลงในซอร์สโค้ด