استراتيجية إصدارات Qiskit SDK
تتبع أرقام إصدارات Qiskit معيار Semantic Versioning.
يتكوّن رقم الإصدار من ثلاثة مكوّنات أساسية: الإصدار الرئيسي والإصدار الثانوي
وإصدار التصحيح. فمثلاً، في رقم الإصدار X.Y.Z، يمثّل X الإصدار الرئيسي
وY الإصدار الثانوي وZ إصدار التصحيح.
التغييرات التي تكسر توافق واجهة برمجة التطبيقات (API) محجوزة للإصدارات الرئيسية فقط. الفترة الدنيا بين أي إصدارَين رئيسيَّين هي سنة واحدة. أما الإصدارات الثانوية، فتُقدّم ميزات جديدة وإصلاحات للأخطاء دون كسر التوافق مع API، وتُنشر بصفة دورية (حالياً كل ثلاثة أشهر) للإصدار الرئيسي الحالي فقط. وتُقدّم إصدارات التصحيح إصلاحات للأخطاء المكتشفة في أحدث إصدار ثانوي لكل سلسلة إصدارات مدعومة بفاعلية (أي الإصدار الرئيسي). نحن ندعم ما يصل إلى سلسلتَي إصدار في آنٍ واحد، وهذا لا يحدث إلا خلال فترة التداخل التي تعقب إطلاق إصدار رئيسي جديد، كما هو موضّح بمزيد من التفصيل أدناه.
جدول الإصدارات
يوجد أدناه جدول إصدارات تقديري:
للاطلاع على جدول الإصدارات المحدَّث، راجع قائمة المعالم في مشروع Qiskit على GitHub، إذ تحتوي دائماً على خطة الإصدار الحالية.
مع إطلاق إصدار رئيسي جديد، يُدعَم الإصدار الرئيسي السابق لمدة لا تقل عن ستة أشهر بإصلاحات الأخطاء فقط، ولمدة سنة كاملة لإصلاحات الثغرات الأمنية. خلال هذه الفترة تُنشر إصدارات تصحيح فقط لذلك الإصدار الرئيسي. يُنشر إصدار تصحيح نهائي عند إيقاف الدعم، ويوثّق ذلك الإصدار نهاية دعم سلسلة ذلك الإصدار الرئيسي. تُعدّ فترة الدعم الأطول للإصدار الرئيسي السابق ضرورية لمنح مستخدمي Qiskit في المشاريع المجاورة وقتاً كافياً لترحيل كودهم البرمجي. لا ينبغي للمكتبات المجاورة التي تعتمد على Qiskit أن ترفع الحدّ الأدنى لإصدار Qiskit المطلوب إلى إصدار رئيسي جديد مباشرةً عقب إطلاقه، لأن قاعدة مستخدمي المكتبة تحتاج إلى وقت للتكيّف مع تغييرات API الجديدة. إن توفير نافذة دعم ممتدة للإصدار الرئيسي السابق من Qiskit يمنح المشاريع المجاورة وقتاً لضمان التوافق مع الإصدار الرئيسي القادم. ويمكن لهذه المشاريع دعم سلسلتَي إصدار في آنٍ واحد لإتاحة مسار ترحيل لمستخدميها.
لأغراض الإصدار الدلالي (Semantic Versioning)، تُعدّ واجهة برمجة التطبيقات
العامة في Qiskit أي وحدة (module) أو صنف (class) أو دالة أو وسيلة (method)
موثّقة وغير مُعلَّمة كخاصة (بادئة _ بالشرطة السفلية). غير أنه يمكن
وجود استثناءات صريحة لبعض واجهات برمجة التطبيقات الموثّقة. في مثل هذه
الحالات، ستكون هذه الواجهات موثّقة بوضوح على أنها لا تُعدّ واجهات مستقرة
بعد، وسيصدر تحذير مرئي للمستخدم عند أي استخدام لهذه الواجهات غير المستقرة.
علاوة على ذلك، في بعض الحالات تُعدّ واجهة مُعلَّمة كخاصة جزءاً من واجهة
برمجة التطبيقات العامة. عادةً لا يحدث ذلك إلا في حالتَين: إما تعريف واجهة
مجردة (abstract interface) حيث يُقصد من الأصناف الفرعية تجاوز/تنفيذ وسيلة
خاصة كجزء من تعريف التطبيق، أو وسائل منخفضة المستوى للاستخدام المتقدم
ذات واجهات مستقرة لكنها غير آمنة للاستخدام العام،
إذ يقع على عاتق المستخدم الحفاظ على ثوابت الصنف/الأمان بنفسه
(المثال الكنسي على ذلك هو وسيلة QuantumCircuit._append).
إصدارات Python المدعومة، والحدّ الأدنى لإصدار Rust المدعوم (لبناء Qiskit من المصدر)، وأي حزم تبعيات Python (بما في ذلك الحدود الدنيا لإصداراتها) التي يستخدمها Qiskit، لا تندرج ضمن ضمانات التوافق العكسي وقد تتغيّر في أي إصدار. فقط الإصدارات الثانوية أو الرئيسية ترفع الحدود الدنيا لمتطلبات استخدام Qiskit أو بنائه (بما في ذلك إضافة تبعيات جديدة)، بينما قد تتضمن إصدارات التصحيح دعماً لإصدارات جديدة من Python أو تبعيات أخرى. في الغالب، لا يُرفع الحدّ الأدنى لإصدار التبعية إلا حين تنتهي فترة دعم الإصدارات القديمة منها، أو حين يتعذّر الحفاظ على التوافق مع أحدث إصدار من التبعية والإصدار القديم منها.
استراتيجية الترقية
عند إطلاق إصدار رئيسي جديد، يُوصى بأن يكون مسار الترقية
هو الترقية أولاً إلى أحدث إصدار ثانوي على الإصدار الرئيسي
السابق. قُبيل إطلاق إصدار رئيسي جديد، سيُنشر إصدار ثانوي
نهائي. هذا الإصدار الثانوي النهائي X.Y+1.0.0 مكافئ لـ
X.Y.0 لكن مع تحذيرات إيقاف (deprecation warnings) لأي تغييرات
في API ستُجرى في سلسلة الإصدار الرئيسي الجديد.
على سب يل المثال، قُبيل إطلاق الإصدار 1.0.0 مباشرةً، سيُنشر الإصدار 0.46.0. سيكون الإصدار 0.46.0 مكافئاً للإصدار 0.45.0 لكنه سيتضمن تحذيرات إيقاف إضافية توثّق تغييرات API التي أُجريت ضمن الإصدار 1.0.0. سيُطبَّق هذا النمط على أي إصدارات رئيسية مستقبلية.
يُنصح مستخدمو Qiskit بالترقية أولاً إلى هذا الإصدار
الثانوي النهائي لرؤية أي تحذيرات إيقاف وضبط استخدامهم لـ Qiskit
قبل تجربة إصدار قد يحمل تغييرات جذرية. سيُدعم الإصدار
الرئيسي السابق لمدة لا تقل عن ستة أشهر لمنح وقت كافٍ
للترقية. من الأنماط الشائعة لإدارة ذلك تحديد حدٍّ أقصى للإصدار
لتجنب استخدام سلسلة الإصدار الرئيسي القادمة حتى تتأكد من التوافق.
فمثلاً، تحديد qiskit<2 في ملف المتطلبات حين يكون الإصدار
الرئيسي الحالي هو 1 يضمن استخدام إصدار من Qiskit
لا يحمل تغييرات جذرية في API.
تحديد سقف للإصدار أقل من الإصدار الرئيسي القادم
يضمن رؤية أي تحذيرات إيقاف قبل
إطلاق إصدار رئيسي.
بدون هذا السقف، يثبّت pip
أحدث إصدار متاح بشكل افتراضي.
صيغة تسلسل QPY متوافقة عكسياً بحيث يمكن لإصدار جديد من Qiskit تحميل ملف QPY
تم توليده بإصدار سابق من Qiskit. لكن الصيغة ليست متوافقة أمامياً، لذا من حيث المبدأ لا يمكن
تحميل ملفات QPY تم توليدها بإصدار أحدث من Qiskit باستخدام إصدار أقدم. لتسهيل ترحيل المستخ دمين عبر إصدارات رئيسية، ستدعم دالة qiskit.qpy.dump() دائماً إصداراً واحداً على الأقل يتداخل بين الإصدار X.0.0 والإصدار X-1.Y.0 (حيث Y هو آخر إصدار ثانوي في
تلك السلسلة). سيُمكّن المعامل qiskit.qpy.dump(..., version=...) من حفظ ملفات بصيغة QPY يمكن تحميلها من كلا الإصدارين الرئيسيين انطلاقاً من الإصدار
الأحدث. راجع مزيداً من التفاصيل في RFC 0020.
الإصدارات التجريبية
لكل إصدار ثانوي ورئيسي، ينشر Qiskit إصدارات تجريبية
متوافقة مع PEP440. عادةً
تأخذ شكل مرشحات الإصدار (release candidates) على هيئة X.Y.0rc1. تمتلك إصدارات rc
سطحاً نهائياً لـ API وتُستخدم لاختبار الإصدار المرتقب.
لاحظ أنه حين يُنشر أحد لاحقات PEP440 التجريبية (مثل a أو b أو pre)،
فإنها لا تحمل نفس ضمانات إصدار rc، وهي
مجرد إصدارات معاينة. قد يتغيّر API بين هذه الإصدارات التجريبية
وال إصدار النهائي بنفس رقم الإصدار. على سبيل المثال، قد يكون لـ 1.0.0pre1
API نهائي مختلف عن 1.0.0.
الإصدارات اللاحقة
إن وُجدت مشكلات في تغليف أحد الإصدارات، قد يُصدر إصدار لاحق
لتصحيح ذلك. تتبع هذه الإصدارات نمط X.Y.Z.1 حيث يشير الرقم الرابع
إلى أنه أول إصدار لاحق للإصدار X.Y.Z.
على سبيل المثال، واجه الإصدار 0.25.2 من qiskit-terra (الاسم القديم لحزمة Qiskit)
مشكلة في نشر حزمة sdist، فصدر الإصدار اللاحق
0.25.2.1 لتصحيح تلك المشكلة. كان الكود متطابقاً،
وقد أصلح 0.25.2.1 مشكلة التغليف فقط.
كيفية إضافة تحذيرات الإيقاف من قِبَل المساهمين
راجع دليل الإيقاف في مستودع Qiskit SDK للاطلاع على تعليمات إضافة تحذيرات الإيقاف إلى الكود المصدري.