إصدار دلالي

Semantic Versioning (SemVer) - عقد حول كيفية عكس رقم الإصدار لطبيعة التغييرات. الشكل: الرائد. قاصر. PATCH [- PRERELEASE] [+ BUILD].

• MAJOR - تغييرات غير متوافقة (كسر).
• MINOR - ميزات/امتدادات متوافقة بشكل متبادل.
• التصحيح - إصلاحات الأخطاء/الأمان المتوافقة مع الخلف.

الهدف: تطور يمكن التنبؤ به لواجهات برمجة التطبيقات والأحداث ومخططات البيانات والقيم الخاصة والتكوينات دون حدوث أعطال مفاجئة للمستهلكين.

1) أرقام الاتفاقية

X.Y.Z[-alpha.1    -rc.1][+build.sha]

التجميعات غير المستقرة ؛ لا تعد بالتوافق.
بناء البيانات الوصفية (+ شا) - لا يؤثر على ترتيب المقارنة، وهو مفيد للتتبع.
حتى 1. 0. 0 يمكن اعتبار أي تغيير كسرًا (ولكن من الأفضل اتباع القواعد منذ البداية).

2) ما الذي يجب مراعاته في الكسر/القاصر/التصحيح

• إصلاحات للأخطاء والأمن دون تغيير العقد.
• تحديثات الالتحام التي لا تؤثر على العقد.
• الاستخدام الأمثل دون تغيير الاستجابات/الأحداث/المخططات.

• أضف مجالات/طرق/نقاط نهاية اختيارية جديدة.
• توسيع قيم enum إذا كان المستهلكون يتحملون قيمًا غير مألوفة.
• مؤشرات قاعدة بيانات جديدة، أعمدة غير قابلة للإلغاء مع أحداث افتراضية جديدة بالإضافة إلى الأحداث القديمة.

• الحقول المحذوفة/المعاد تسميتها، الأنواع المتغيرة، إلزامية.
• تغيير الدلالات/الحالات/رموز الخطأ.
• تغيير شكل التسلسل، نظام المفتاح، بروتوكول النقل.
• ضغط/دمج المواضيع، نقل معنى الحدث، تغيير مخطط التقسيم.
• هجرات قاعدة البيانات التي تتطلب تبديل «مرحلتين» دون توافق خلفي.

3) إصدار القطع الأثرية

3. 1 راحة

البدائل: «URI/v1/...»، الرؤوس ('قبول: طلب/vnd. acme. لعبة + json; النسخة = 1 ')، المعلمة.
التوصية: صيغة في أوري لواجهات برمجة التطبيقات العامة ؛ للداخلية - من خلال التفاوض بالرأس ج.
MINOR: إضافة مجالات اختيارية، مرشحات/موارد جديدة ؛ لا تغير الإجابات الحالية.
التصحيح: الإصلاحات، تحسين التعريف، الفرز المستقر.

3. 2 gRPC

تغيير التوقيعات/الأنواع → الرئيسية (حزمة/خدمة جديدة: 'acme. المحفظة. v2 ').
حقول جديدة - توصف بأنها اختيارية ؛ يجب أن يتجاهل الخادم المجهول.
لا نحذف الحقول: «depricket + reserve a number»، تحذف - فقط في MAJOR التالي.

3. 3 رسم بياني QL

الصغرى: مجالات/أنواع/استفسارات جديدة ؛ الإزالة - من خلال «@ deprecated» + نافذة الهجرة، الإزالة الكاملة - MAJOR.
تغيير nullable→non - لا - الرائد.

3. 4 أحداث وموضوعات (كافكا/SQS)

المخططات في سجل المخطط: تطور المواد المضافة (أضف حقول بها تخلف عن السداد).
نسخة جديدة غير متوافقة → موضوع/موضوع جديد ('bet. setted. v2 ').
مفتاح التقسيم ثابت داخل MAJOR.

3. 5 مخططات DB

1. يضاف عمود (غير قابل للإلغاء/الافتراضي) →

2. املأ الردم →

3. ترجمة → يقرأ

4. إزالة القديم (الرائد فقط).

نوع التغيير/PK/التفرد - MAJOR، تحت phicheflag والمدخل المزدوج.

3. 6 SDK/CLI

الأساليب العامة/التوقيعات هي نفس القواعد.
للتوليد الذاتي (OpenAPI/Proto) - نسخة من اسم الدفعة والتحف.

4) سياسة الحرمان ودورة الحياة

يسبق كل تغيير كسر بالاكتئاب (عادة 90-180 يومًا للخارج، 30-60 يومًا للداخلي).
الاتصالات: سجل التغيير، والبريد الإلكتروني/الخطابات الشبكية للشركاء، واللافتات في بوابة المطورين.
وضع التشغيل المزدوج: الاحتفاظ بـ «v1» و «v2» بالتوازي، ومراقبة حصة حركة المرور «v1».
رؤوس الغروب (REST): "غروب الشمس: 2026-03-31"، "الرابط: <url> ؛ rel = «الاستنكار».

5) التفاوض على النسخة

يرسل العميل الإصدار المطلوب + الإصدار الأقصى المدعوم (على سبيل المثال، «Accept-Version: 1.2»).
يستجيب الخادم بـ «Content-Version: 2» إذا كان بإمكانه الترويج.
في البروتوكولات ثنائية الاتجاه (WebSocket، gRPC) - تبادل إطارات Hello مع «الإصدارات المدعومة».

6) تكامل محول المزود (ACL)

يقوم المزود الخارجي بتغيير المخطط - داخل المحول نحتفظ بمخططات v1/v2 ونطلق MINOR للحدث الداخلي، مع الحفاظ على عقد النطاق الخاص بنا.
إذا كانت التغييرات الخارجية تشق طريقها إلى الداخل، فهذا هو MAJOR لحدث المجال الخاص بنا وموضوع جديد.

7) Changelog وارتكاب الملصقات

• «الدهون:»... → الصغرى
• 'fix:... "/" عمل روتيني "،" مستندات "،" perf "(بدون عقد) → PATCH
• «الدهون!: »/« الإصلاح!: »/« refactor!:» أو «كسر التغيير:» في الجسم → الرئيسي

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) أتمتة الإصدار

CI: مصدقات الدائرة (OpenAPI/Protobuf/Avro/JSON-Schema)، اكتشاف الكسر المنتشر. أكثر

SemVer-bot: تحليل الالتزامات التقليدية → تحسب النتوء (الرئيسي/الثانوي/التصحيح)، تضع علامة، تولد التغيير.
CD: نشر وإطلاق منفصلين (phicheflags/التكوينات تنشط النسخة الجديدة).
التحكم: لا تنشر «أحدث» على PRO حتى نجاح الكناري و SLOs المتفق عليها.

9) دلالات التشكيلات والسياسات

ثانياً - مجالات/قواعد اختيارية جديدة

التكوينات (YAML/JSON) لديها أيضًا نسخة مخطط: «مخطط _ إصدار: 3».
دعم v2/v3 في المصادقة ؛ مهاجر التهيئة مع تقرير عدم التوافق.

10) اختبار التوافق

اختبارات العقود التي يحركها المستهلك (الميثاق): لكل تكامل.
اختبارات تطور المخطط: تشغيل الحمولات القديمة على مخطط جديد والعكس صحيح.
إعادة التشغيل - يلعب حركة الإنتاج «v1» إلى «v2» في الظل.
قائمة على الملكية: مقاومة الحقول غير المألوفة/enum.

11) قابلية الملاحظة حسب النسخة

Tag metrics/logs: 'api _ version', 'schema _ version', 'event _ version'.
لوحات معلومات الهجرة: مشاركة حركة المرور حسب الإصدارات، خطأ/زمن انتقال بواسطة 'v1/v2'.
تنبيهات: إذا لم تنخفض 'v1' كما هو مخطط لها ؛ نمو 4xx/5xx بعد الإصدار «v2».

12) أنماط الهجرة دون توقف

توسيع عقد الهجرة → → (БД).
الكتابة المزدوجة + قارن الاختلافات قبل تبديل القراءة.
قارن الظل بالترتيب/القواعد.
الكناري حسب المستأجر/المنطقة ؛ أعلام للتراجع السريع.
نوافذ Read-compat/Write-compat: يقرأ الإصدار الجديد البيانات القديمة، لكنه يكتب بتنسيق جديد.

13) الأنماط المضادة

«نسخة في كل حقل» بدلاً من إصدار المورد/الحدث.
تغييرات كسر مخفية تحت MINOR (على سبيل المثال، تغيير التخلف عن السداد).
إزالة المقاييس غير المصنعة بدون نوافذ واستهلاك.
«إلى الأبد v1»: لا توجد خطة لإزالة الإصدارات القديمة من الديون الفنية → ونقاط الضعف.
امزج نسخة العمل ونسخة صورة الحاوية.

14) Veronizing Policy Checklist

• شكل النسخة الثابتة ومصادر الحقيقة (قلم المحكمة/البوابة).
• قائمة معتمدة بالمعايير الفاصلة حسب القطع الأثرية (REST/gRPC/GraphQL/events/DB).
• عملية الإزالة: التوقيت، الاتصالات، غروب الشمس/اللافتات، تشغيل مزدوج.
• مدقق diff التلقائي والالتزامات التقليدية.
• لوحات التحكم في الاستهلاك.
• كتب اللعب الخاصة بالهجرة (التوسع/الهجرة/العقد، الكتابة المزدوجة، الظل).
• التكوينات و SDKs لها إصداراتها وحالتها الخاصة.
• توثيق «كيفية اختيار نسخة» للعملاء و «كيفية الترقية» للأفرقة.

15) أمثلة على الإصدار (حالات iGaming)

"BetSettled v1" event → "v2": تمت إضافة "void _ reason" (اختياري) و "ضريبة. (اختياري) - MINOR. أعيدت تسميته «payout'→'win_amount» - MAJOR، موضوع جديد.
REST'/wallets/transfer ': مرشح مضاف' ؟ المستأجر = '- MINOR. تغيير رمز الخطأ '409'→'422' - MAJOR.
الرسم البياني QL: مشغل مميز. العمر «مثل» @ disprecated «لصالح» Player. Age Group '- الإصدار في MINOR، الحذف في MAJOR بعد الفترة X.
DB: تمت إضافة العمود «علاوة _ رهان _ يسار» غير قابل للإلغاء - MINOR. جعل غير باطل وحذف «علاوة _ يسار» - MAJOR (عبر التوسيع/العقد).

خامسا - الاستنتاج

الإصدار الدلالي لا يتعلق بالأرقام، بل يتعلق بالثقة والقدرة على التنبؤ. تسمح القواعد الواضحة والفحوصات الآلية والاكتئاب الخاضع للرقابة والقياس عن بعد الشفاف لواجهات برمجة التطبيقات والأحداث والمخططات الخالية من الألم بالتطور للتكامل - وإطلاق التغييرات بشكل متكرر وآمن وهادف.