إصدار دلالي

إصدار دلالي

1) ما هو SemVer ولماذا هو مطلوب

• التغييرات الرئيسية.
• MINOR هي ميزة جديدة متوافقة مع واجهة برمجة التطبيقات.
• التصحيح - إصلاحات عيوب قابلة للعكس.

الهدف: الاتفاق على استقرار العقود وخفض تكلفة التحسينات.

2) صيغة النسخة

• الرائد. قاصر. التصحيح [- PRERELEASE] [+ BUILD] "

`1. 4. 7 'هو إطلاق مستقر.
`1. 5. 0-rc. 2 '- ما قبل الإفراج (مرشح الإفراج رقم 2).
`2. 0. 0 + لينكس. arm64 - build metadata (لا تؤثر على مقارنة النسخ).

1. أولاً، تتم مقارنة «MAJOR»، ثم «MINOR»، ثم «PATCH».

2. الإصدارات المسبقة أصغر من الإصدار المستقر المقابل: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. لا يؤثر بناء البيانات الوصفية ('+...') على الترتيب: '1. 2. 0+001 == 1. 2. 0`.

3) ما الذي يعتبر كسر التغيير

• حذف/إعادة تسمية/تغيير توقيع الطرق العامة/نقاط النهاية.
• تغيير شكل المدخلات/المخرجات (مخطط JSON، الأنواع).
• تعديل عقود الخطأ (الرموز/الهياكل).
• تغيير الآثار الجانبية/اتفاقيات البيئة المستدامة (على سبيل المثال، الحدود الصارمة أو الحقول الجديدة المطلوبة).

عدم كسر (إذا تم تنفيذه بشكل صحيح): إضافة حقول اختيارية، وتوسيع enum بقيم جديدة (إذا تجاهلها العميل)، ونقاط نهاية جديدة، وأعلام جديدة ذات تخلف عن السداد لا تؤثر على المكالمات الحالية.

4) الإصدارات المسبقة واستراتيجيات القنوات

• العلامات: «ألفا»، «بيتا»، «آر سي». مثال: '2. 3. 0-بيتا. 3`.
• القنوات: → الليلي ألفا → بيتا → rc → مستقر.
• السياسة العامة: لا ينبغي أن تقع عمليات الإطلاق المسبقة كتبعيات متعدّدة لتجمعات الإنتاج الافتراضية.

5) نطاقات الإصدار ودقة القيود

5. 1 عقدة/npm (افتراضي SemVer)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(يسمح MINOR/PATCH، يصلح MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(يسمح باتش داخل MINOR).
`1. 4. x 'هو أي رقعة في 1. 4.
الدبوس الدقيق: '1. 4. 2`.

5. 2 بايثون (PEP 440، pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- حدود صريحة.

5. 3 مافن/جرادل (جافا)

`[1. 4,2. 0) - شامل/حصري.
يوصى بالركل الصارم للقطع الأثرية الحرجة للطعام.

5. 4 وحدات Go

دائما أكمل علامات «V MAJOR». قاصر. PATCH '؛' v2 + 'تتطلب لاحقة الوحدة '/v2'.

التوصية: للتطبيقات - الدبابيس الدقيقة (المباني القابلة للتكرار). بالنسبة للمكتبات - نطاقات الرعاية (تسهيل التحديثات دون كسر).

6) CHANGELOG и الالتزامات التقليدية

سجل التغيير المنظم يحسن الشفافية.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: «الفذ»، «الإصلاح»، «perf»، «المستندات»، «refactor»، «العمل الروتيني» и т. д.
علامة تعجب أو كتلة «كسر التغيير» تعلن رائدًا.
تم إنشاء CHANGELOG من تاريخ الالتزامات (ملاحظات الإصدار بواسطة الروبوتات).

7) سياسة تحويل واجهة برمجة التطبيقات

واجهات برمجة التطبيقات العامة: SemVer صارمة ؛ كسر → الرائد.
HTTP/REST: الإصدار بواسطة URL/Header: '/v1/... '، '/v2/...' أو 'قبول: طلب/فند. org. الخدمة. v2 + json '.
مخططات JSON: تمديدات طفيفة - مجالات اختيارية جديدة ؛ رئيسية - حذف/تغيير إلزامي.
gRPC/Protobuf: إضافة حقول جديدة بأرقام جديدة ؛ لا تعيد استخدام أرقام الحقول التي تحذف → الاستنكاف، وليس كسر الأرقام الموجودة.

8) مخططات البيانات والهجرة

يتم تزامن عمليات نقل قواعد البيانات مع إصدارات التطبيق @ 1. 8. 0 «يتطلب» schema @ 1. 8. x '.
لكسر تغييرات المخطط - المراحل: توسيع (إضافة)، ترحيل، عقد (حذف). قم بالترقية إلى MAJOR فقط عند حذف العقد القديم.
دعم الكتابة/القراءة المزدوجة طوال مدة الهجرة.

9) Monorepos و microservices

حزمة متعددة: لكل حزمة «حزمة رئيسية» خاصة بها. قاصر. PATCH '؛ دورة إطلاق الجذر المشتركة للتحف الفوقية فقط.

• الإصدارات المستقلة (Lerna/Changesets) - تزيد من العزلة.
• خطوة القفل - اتصال أسهل، ولكن المزيد من MAJORS الخاطئة.
• بالنسبة للخدمات الصغيرة، قم بإصلاح العقود (OpenAPI/Protobuf) بإصدار منفصل: 'contract @ 2. 1. 0 '، تتبعها الخدمة.

10) التشغيل الآلي للإصدارات في CI/CD

• "fix" → "PATCH"، "feat' →" MINOR "،"! "/" BREAKING "→" MAJOR ".

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

توليد CHANGELOG، ونشر ملاحظات الإصدار، وتحديث التبعيات في GitOps repo، والتحقق من أن «الرئيسي» يشير دائمًا إلى آخر علامة مستقرة.

11) سياسة الحرمان

الإعلان: وضع علامة على الوظيفة كما تم استبعادها في إصدار MINOR، وإعطاء مصطلح EOL (على سبيل المثال 90 يوما).
إمكانية الرصد: تسجيل استخدام نقاط النهاية القديمة مع سياق المستخدم/المستأجر.
حذف: في الميجور التالي. وثق مسار الهجرة.

12) الأمثلة والنماذج

12. 1 التعبير العادي للتحقق من صحة SemVer

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 أمثلة على المقارنات

`1. 2. 3` < `1. 10. 0 '(مقارنة طفيفة).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3 + البناء. 5` == `1. 2. 3`.

12. 3 سياسة التبعية (مثال YAML)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

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

باستخدام «أحدث »/العلامات العائمة في الحافز.
تحسين كبير بدون أعطال حقيقية («إصدارات التسويق»).
تغييرات كسر مخفية تحت ستار «PATCH».
الإطلاقات المسبقة في التبعيات المتعدّدة لتطبيقات الإنتاج.
قم بتغيير القطعة الأثرية بدون علامة جديدة (إصدارات قابلة للتغيير).
عدم اتساق إصدارات الرموز ومخططات قواعد البيانات.

14) قائمة التنفيذ المرجعية (0-45 يوما)

0-10 أيام

قبول SemVer كمعيار إلزامي، والموافقة على معايير كسر.
قم بتضمين الالتزامات التقليدية وقالب العلاقات العامة مع مجال «كسر التغيير».

11-25 يومًا

قم بتوصيل semantic-release/changesets، CHANGELOG autogeneration.
قم بتهيئة توقيع ونشر القطع الأثرية مقابل علامة vX. YZ '.

26-45 يومًا

أدخل سياسة الاستنكار والقياس عن بُعد لاستخدام واجهة برمجة التطبيقات القديم.
تزامن إصدارات العقود (OpenAPI/Proto) والخدمات.
حظر «أحدث» العلامات القابلة للتغيير على مستوى السياسة (لوائح OPA/CI).

15) مقاييس النضج

% من القطع الأثرية التي نشرتها علامة SemVer فقط.
متوسط وقت الانتقال بين إصدارات MINOR.
عدد الحوادث بسبب تغييرات الكسر الخفية.
تغطية الالتزامات التقليدية في المستودعات (> 95٪).
نسبة التبعيات بدون نطاقات عائمة في المنتج (> 90٪).

16) عندما لا تكون هناك حاجة إلى SemVer

النماذج الأولية السريعة الداخلية بدون مستهلكين خارجيين (الإصدار القديم مناسب).
بيانات/نماذج ذات خصائص تجريبية (صيغة أفضل للنموذج/المخطط مع التوافق على مستوى المحول).
حزم المحتوى بدون واجهة برمجة تطبيقات عامة مستقرة.

17)

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