الإصدارات والإيقاف
كيف تُرقَّم الإصدارات
- الإصدار الرئيسي في المسار:
/v1/…. لا يتغير بشكل يكسر تكاملك ما دامv1قائماً. - إصدارات الميزات داخل v1:
v1.0وv1.1وv1.2. كل عملية فيopenapi.yamlتحملx-release، والعمليات المتاحة اليوم تحملx-implemented: true. التفاصيل في سجل التغييرات. - إصدار العقد:
1.0.0-draft.1(حقلinfo.version).
قبل إطلاق الإصدار وبعده
ننشر العقد قبل التنفيذ لتبني بالتوازي معنا. قبل أن يُطلق إصدار قد تتغير أشكاله، ونسجّل كل تغيير في سجل التغييرات. بعد إطلاقه يتغير v1 بالإضافة فقط.
تغييرات قد نجريها داخل v1 دون إشعار مسبق
- نقاط نهاية جديدة وأنواع أحداث ويب هوك جديدة
- معاملات استعلام وحقول طلب اختيارية جديدة
- حقول جديدة في الاستجابات ومحتوى الويب هوك
- قيم جديدة في تعداد (enum) موجود
- رموز أخطاء جديدة (كلٌّ منها يستخدم حالة HTTP الموثقة)
- ترويسات استجابة اختيارية جديدة
- قبول مدخلات كانت تُرفض
ابنِ تكاملك ليتحمّلها: تجاهل الحقول التي لا تعرفها، وتعامل مع قيم التعداد غير المعروفة بلطف، ولا تعتمد على ترتيب الحقول، وتفرّع حسب code وليس title في الأخطاء، وتعامل مع رمز خطأ غير معروف حسب حالة HTTP.
التغييرات الجذرية تذهب إلى v2
لا نجري أياً مما يلي داخل v1:
- حذف أو إعادة تسمية نقطة نهاية أو حقل أو معامل أو قيمة تعداد أو حدث
- تغيير نوع حقل أو صيغته أو معناه
- جعل معامل أو حقل اختياري إلزامياً
- رفض مدخلات كانت تُقبل
- اشتراط صلاحية مختلفة أو إضافية لنقطة نهاية قائمة
- تغيير طريقة التوقيع أو صيغة الأخطاء
إذا احتجنا إلى أي منها، نطلق /v2 إلى جانب /v1، ويبقى v1 يعمل لمدة [مدة الإشعار قيد التأكيد] على الأقل من تاريخ إعلان إيقافه.
كيف نعلن الإيقاف
- مدخل إيقاف مُعلن في سجل التغييرات بتاريخ الإيقاف النهائي.
- تعليم العملية أو الحقل بـ
deprecated: trueفيopenapi.yaml، فيظهر في المرجع ومجموعة Postman. - بريد إلى جهات الاتصال المسجلة للمطوّرين والشركات التي تستخدم ما سيتوقف.
- ترويستا
DeprecationوSunsetعلى استجابات العمليات المعنية حتى تاريخ الإيقاف.
المعاينات
الميزات المعلَّمة بـ «معاينة» — مثل OAuth حالياً — لا تشملها هذه السياسة حتى تُطلق رسمياً، وقد تتغير دون فترة إشعار.