سياسة الإصدارات والاستقرار والإهمال والدعم

لمحة سريعة

تحمل كل صفحة من توثيق ⁨NextPDF⁩ حقول دورة حياة في بياناتها الأمامية: stability وsince وdeprecated_since وreplaced_by وversion_lifecycle وeol_date. وتلك الحقول تُرمّز أصلًا عقد دعم. تذكر هذه الصفحة ذلك العقد في مكان واحد ليستطيع فريق إنتاج قراءة بيانات أي صفحة وتقييم خطر تثبيت إصدار.

يتّبع ⁨NextPDF⁩ الإصدار الدلاليّ ⁨2.0.0⁩ لأرقام إصداراته و⁨Conventional Commits⁩ ⁨1.0.0⁩ لتوليد سجلّ التغييرات. وتحكم القواعد نفسها واجهة مزوّد الخدمة (العقود العامة في NextPDF\Contracts وNextPDF\Event)؛ انظر قواعد استقرار ⁨SPI⁩ لميكانيكا وسم @stability لكل عقد. هذه الصفحة هي السياسة الأوسع التي تخصّصها قواعد ⁨SPI.⁩

الإصدار الدلاليّ لـ⁨NextPDF⁩

إصدار الإطلاق MAJOR.MINOR.PATCH. والموضع الذي يتغيّر يخبرك بما يمكن أن يتغيّر في شيفرتك:

الزيادة	ماذا تعني	ما قد ينكسر
رئيسيّ (3.x ← 4.0.0)	التغييرات الكاسرة مسموح بها.	قد يغيّر عقد stable توقيعه أو يُحذف؛ وقد يُحذف رمز مُهمَل وُسِم في الرئيسيّ السابق؛ وقد يتغيّر السلوك الافتراضيّ.
ثانويّ (6.0 ← 6.1.0)	إضافات متوافقة عكسيًا.	لا شيء لعقد stable. لا تكتسب واجهة مستقرّة منشورة أي طرائق مطلوبة جديدة؛ يأتي النموّ من عقود/واجهات جديدة، وطرائق اختيارية على أصناف ملموسة، وخيارات مُنشئ/تهيئة جديدة لها قيم افتراضية. وقد يتغيّر عقد experimental هنا، بإشعار إهمال أولًا.
تصحيحيّ (4.0.0 ← 3.2.1)	إصلاحات أخطاء متوافقة عكسيًا.	لا شيء مقصود. يتقارب السلوك نحو العقد الموثّق.

القاعدة العملية لسطح stable: قيد ⁨Composer⁩ مثل ‏^3.2 يتلقّى كل إصدار ثانويّ وتصحيحيّ من خطّه الرئيسيّ دون تغيير كاسر. ولا تهبط التغييرات الكاسرة إلا على حدّ رئيسيّ.

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

ثبّت أضيق (مثلًا ~3.2.0) حين تعتمد على عقد experimental، لأن عقد experimental قد يتغيّر في إصدار ثانويّ.

وسوم الاستقرار

يستمدّ حقل stability للصفحة، ووسم @stability المصدريّ للعقد، من المفردات نفسها. ويذكر الوسم قوة وعد التوافق.

الوسم	ماذا يضمن	أين يتغيّر
stable	جاهز للإنتاج. آمن للاعتماد عليه. لا تغيير كاسر في إصدار ثانويّ أو تصحيحيّ. لا تكتسب واجهة مستقرّة (مثل ⁨SPI⁩ ‏NextPDF\Contracts) أي طرائق مطلوبة جديدة في ثانويّ أو تصحيحيّ — يصل النموّ المتوافق عكسيًا على عقد جديد، أو طريقة اختيارية على صنف ملموس، أو عبر خيارات مُنشئ/تهيئة لها قيم افتراضية.	إصدار رئيسيّ فقط.
beta	مكتمل الميزات وقابل للاستخدام، لكن السطح غير مُجمَّد بعد. عامِله مثل experimental للتثبيت: غلّفه أو ثبّته بإحكام.	قد يتغيّر في إصدار ثانويّ، بإشعار إهمال أولًا.
experimental	قابل للاستخدام، لكنه غير مُجمَّد صراحةً. قد يشحن ⁨NextPDF⁩ تنفيذ محرّك مختبرًا بينما لا يزال العقد العام يتحرّك.	قد يتغيّر في إصدار ثانويّ، بإشعار إهمال أولًا.
deprecated	مُجدوَل للإزالة. تذكر الصفحة أو العقد بديله والرئيسيّ الذي يُزال فيه.	يُزال في الرئيسيّ التالي؛ لا في ثانويّ أو تصحيحيّ أبدًا.

عقدا البثّ NextPDF\Contracts\CursorInterface و NextPDF\Contracts\StreamingWriterInterface مثالان حقيقيّان على سطوح experimental: يشحن ⁨NextPDF⁩ تنفيذات نهائية مختبرة، لكن العقد العام قد يتغيّر في إصدار ثانويّ. ثبّت بإحكام أو غلّف عقدًا كهذا خلف مهايئك الخاص قبل أن تعتمد عليه في الإنتاج.

دورة حياة الإهمال

الإهمال مسار معرَّف من أربع خطوات. وهو يسمّي البديل دائمًا، وتُؤجَّل الإزالة دائمًا إلى حدّ رئيسيّ:

1. الوسم. يضبط المالك @stability deprecated على عقد (أو deprecated_since على صفحة) ويسجّل البديل والرئيسيّ المُزيل. وعلى صفحة، deprecated_since هو الإصدار الذي أدخل الإهمال وreplaced_by هو مسار الخَلَف المعياريّ.
2. الإشعار. يُعلَن الإهمال في سجلّ التغييرات للإصدار الذي يَسِمه.
3. التداخل. يتعايش السطح المُهمَل وبديله إصدارًا ثانويًا واحدًا على الأقلّ، فتستطيع الترحيل دون يوم انقلاب.
4. الإزالة. يُزال السطح في الإصدار الرئيسيّ المذكور. ولا تحدث الإزالة في إصدار ثانويّ أو تصحيحيّ أبدًا.

مثال على مستوى الصفحة اجتاز المسار كاملًا: وُسِمت وصفة /docs/cookbook/php/sign-pades/ القديمة بـdeprecated_since: "3.0.0" مع replaced_by: /docs/cookbook/php/sign-pades-b-b/، وتعايشت مع خَلَفها طوال نافذة التداخل، ثم أُزيلت منذ ذلك الحين — إذ يجيب المسار القديم الآن بإعادة توجيه دائمة إلى وصفة الخَلَف، فتظل الروابط المكتوبة نحو الصفحة المُهمَلة تعمل بعد الإزالة.

خطّط للترحيل بمجرد وسم سطح بـdeprecated. ولأن البديل مذكور دائمًا ويتداخل الاثنان ثانويًا واحدًا على الأقلّ، تستطيع الانتقال قبل وصول الرئيسيّ المُزيل.

دورة حياة الإصدار ودعم الأمان

يصنّف حقل version_lifecycle كيف يُصان خطّ إصدار موثَّق. والقيم هي:

version_lifecycle	المعنى	يتلقّى
active	الخطّ الحاليّ تحت التطوير النشط.	الميزات والإصلاحات وإصلاحات الأمان.
lts	خطّ دعم طويل الأمد.	الإصلاحات وإصلاحات الأمان لنافذة دعمه.
maintenance	تجاوز التطوير النشط، لا يزال مُصانًا.	إصلاحات الأمان وإصلاحات الأخطاء الجادّة.
frozen	لا تغيير وظيفيّ آخر مخطَّط.	إصلاحات الأمان فقط، حيثما انطبق.
eol	نهاية العمر.	لا شيء. الترقية مطلوبة.

حين يبلغ خطّ نهاية عمره، يسجّل eol_date له التاريخ ‏(⁨ISO 8601،⁩ ‏YYYY-MM-DD). وصفحة بـversion_lifecycle: eol وeol_date ماضٍ إشارة للترحيل عن ذلك الخطّ: فهو لم يعد يتلقّى إصلاحات، بما فيها إصلاحات الأمان.

هذا بيان سياسة، لا وعد تقويم. تخبرك الحقول بـفئة الدعم التي يكون فيها خطّ؛ راجع سجلّ التغييرات وملاحظات الإصدار للإصدار المحدّد الذي يحمل إصلاحًا معيّنًا. وتُسنَد إصلاحات الأمان للخطوط التي لا تزال دورة حياتها تشملها (active وlts وmaintenance)، لا للخطوط الموسومة frozen-دون-انطباق أو eol.

نافذة دعم إصدار ⁨PHP⁩

يتطلّب ⁨NextPDF Core⁩ ‏⁨PHP⁩ ‏>=8.4 <9.0. وتلك النافذة مُعلنة في composer.json للمحرّك وهي المصدر الوحيد للحقيقة؛ وتتطلّب الحزم المدفوعة ‏(nextpdf/pro وnextpdf/enterprise) المدى نفسه.

• إن الحدّ الأدنى ‏(>=8.4) هو بيئة التشغيل الدنيا. ورفعه تغيير كاسر يهبط على حدّ رئيسيّ فقط.
• إن الحدّ الأعلى ‏(<9.0) يستثني الرئيسيّ التالي لـ⁨PHP⁩ حتى يُتحقَّق منه. ويُضاف دعم رئيسيّ ⁨PHP⁩ جديد في إصدار ⁨NextPDF،⁩ لا يُفترَض.

تحمل صفحات التوثيق أيضًا قائمة compatibility بالإصدارات الثانوية لـ⁨PHP⁩ التي تُتحقَّق الوصفة عليها. وقد تُدرج صفحة ثانويّات أقدم (مثلًا ["8.1", "8.2", "8.3", "8.4"]) حيث تكون الوصفة قابلة للنقل، بينما تبقى أرضية تثبيت المحرّك الصارمة >=8.4. وعند الشكّ، يفوز قيد composer.json على تلميح compatibility لصفحة.

كيف تقرأ بيانات دورة حياة صفحة الأمامية

استخدم هذه الحقول الستة لتقييم أي صفحة قبل أن تبني عليها:

الحقل	النوع	كيف تقرؤه
stability	stable | beta | experimental | deprecated	وعد التوافق للسطح الذي توثّقه الصفحة.
since	⁨SemVer⁩ ‏(مثلًا "3.1.0")	الإصدار الذي أدخل السطح الموثَّق. يجب أن يكون تثبيتك بهذا الإصدار على الأقلّ.
deprecated_since	⁨SemVer⁩ أو فارغ	إن ضُبط، فالسطح مُهمَل؛ والقيمة هي الإصدار الذي أهمله. الفارغ يعني غير مُهمَل.
replaced_by	مسار موقع أو فارغ	عند الإهمال، صفحة الخَلَف المعياريّ للترحيل إليها.
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⁩، وغير مُهمَل، ويقع على الخطّ المُصان نشطًا. يمكنك الاعتماد عليه تحت قيد رئيسيّ ^. وصفحة بـ stability: deprecated وreplaced_by غير فارغ إشارة ترحيل: اقرأ صفحة الخَلَف وخطّط للانتقال قبل الرئيسيّ التالي.

المطابقة

تتوافق هذه السياسة مع الإصدار الدلاليّ ⁨2.0.0⁩ لترقيم الإصدارات ومع ⁨Conventional Commits⁩ ⁨1.0.0⁩ لتوليد سجلّ التغييرات. ونافذة دعم ⁨PHP⁩ هي قيد >=8.4 <9.0 المُعلن في composer.json للمحرّك. لا تدّعي هذه الصفحة أي ادعاء معياري خاص بها؛ فهي توثّق عقد الدعم الذي تُرمّزه حقول دورة الحياة في البيانات الأمامية أصلًا.

انظر أيضًا

• قواعد استقرار ⁨SPI⁩ — وسم @stability لكل عقد وأصناف وعد التوافق العكسيّ الأربعة (واجهة، تعداد، كائن قيمة مُجمَّد، تجريبيّ).
• مصفوفة دعم ⁨CSS⁩ — حالة الدعم المُدقَّقة لكل وحدة لخط أنابيب عرض ⁨HTML⁩ و⁨CSS.⁩
• فهرس المرجع — نقطة الدخول لمواد مرجع ⁨API⁩ والتهيئة والتوافق.