إدارة الإصدارات والترقيات

يتتبع FORGE الإصدار المستخدم لتوليد مشروعك. عندما يُضيف إصدار FORGE جديد ميزات، أو يُصلح أخطاء، أو يُحسّن الكود المُولّد، يُطبّق نظام الترقية تلك التغييرات على مشروعك الحالي بدون الكتابة فوق عملك المخصص.

إصداران منفصلان

هناك رقما إصدار مختلفان يجب الانتباه لهما:

┌─────────────────────────────────────────────────────┐
│  1. إصدار FORGE CLI                                 │
│     الأداة المُثبّتة على جهازك                      │
│     مثال: forge v2.1.0                              │
│                                                     │
│  2. إصدار FORGE للمشروع                             │
│     الإصدار الذي ولّد/آخر ترقية لمشروعك             │
│     مُخزّن في forge.yaml و forge.lock               │
└─────────────────────────────────────────────────────┘

يمكن أن يختلف هذان الإصداران. قد يكون لديك FORGE CLI v2.1.0 مُثبّتاً، لكن مشروعك أُنشئ بـ v2.0.0. نظام الترقية يجسر هذه الفجوة.

تتبع الإصدارات

forge.yaml

تُخزّن إعدادات المشروع إصدار FORGE:

yaml

# forge.yaml
name: myapp
forge_version: 2.0.0
backend: rust
frontend: nextjs
# ...

forge.lock

يحتوي ملف القفل معلومات تفصيلية عن الإصدار والسلامة:

yaml

# forge.lock
forge_version: 2.0.0
created_at: 2026-01-20T10:00:00Z
last_upgraded: 2026-01-20T10:00:00Z

templates:
  base: 2.0.0
  crm: 1.0.0          # إذا كانت وحدة CRM مُثبّتة

checksums:
  migrations: sha256:abc123...
  seeders: sha256:def456...

files:
  "apps/api/src/routes/mod.rs":
    type: managed
    checksum: sha256:def456

  "apps/web/src/app/layout.tsx":
    type: template
    original_checksum: sha256:ghi789
    current_checksum: sha256:ghi789

نصيحة

دائماً أضف forge.lock إلى التحكم بالإصدارات. هذا يضمن أن كل عضو في الفريق يعمل بنفس سياق إصدار FORGE، ويمكن تطبيق الترقيات بشكل متسق.

الإصدارات الدلالية

يتبع FORGE الإصدارات الدلالية:

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── إصلاحات أخطاء، بدون تغييرات كاسرة
  │     └──────── ميزات جديدة، متوافقة مع الخلف
  └────────────── تغييرات كاسرة، تتطلب ترحيل

ما يُشكّل تغييراً كاسراً

نوع التغيير	كاسر؟	مثال
أمر CLI جديد	لا	إضافة `forge deploy:k8s`
نقطة نهاية API جديدة	لا	إضافة `GET /api/v1/stats`
تغيير تنسيق استجابة API	نعم	تغيير `{ user: {...} }` إلى `{ data: {...} }`
تغيير اسم عمود قاعدة بيانات	نعم	إعادة تسمية `users.name` إلى `users.full_name`
إزالة أمر CLI	نعم	إزالة أمر مُهمل
تغيير السلوك الافتراضي	نعم	تغيير المصادقة الافتراضية من email إلى mobile

التحقق من الترقيات

قبل الترقية، تحقق مما تغيّر:

bash

forge upgrade:check

المخرجات:

إصدار المشروع الحالي: 2.0.0
أحدث إصدار FORGE:    2.1.0
نوع الترقية:         minor

التغييرات في 2.1.0:
  + إضافة دعم لغات RTL
  + إضافة تحديد معدل طلبات مفاتيح API
  + تحسين سجل التدقيق
  + 1 ترحيل جديد

لا توجد تغييرات كاسرة.
شغّل `forge upgrade:apply` للتطبيق.

تحذير

دائماً اقرأ سجل التغييرات قبل الترقية. لترقيات الإصدارات الكبرى، راجع مستند BREAKING_CHANGES.md بعناية وخطط للترقية خلال فترة تطوير.

عملية الترقية

تشغيل forge upgrade:apply يتبع عملية منظمة من ست خطوات:

┌─────────────────────────────────────────────────┐
│ 1. فحص الإصدار                                  │
│    قراءة forge.lock → مقارنة مع الأحدث         │
│    تحديد نوع الترقية (major/minor/patch)       │
├─────────────────────────────────────────────────┤
│ 2. فحص التوافق                                  │
│    التحقق من عدم تعارض الكود المخصص            │
│    فحص توافق القوالب والوحدات                   │
├─────────────────────────────────────────────────┤
│ 3. النسخ الاحتياطي                              │
│    نسخ احتياطي لـ forge.yaml، forge.lock        │
│    نسخ احتياطي لقاعدة البيانات (pg_dump)        │
│    إنشاء git commit أو stash                   │
├─────────────────────────────────────────────────┤
│ 4. تطبيق الترحيلات                              │
│    تشغيل ترحيلات قاعدة البيانات الجديدة         │
│    تحديث checksums في forge.lock               │
├─────────────────────────────────────────────────┤
│ 5. تحديث الكود                                  │
│    تحديث تلقائي للملفات المُدارة               │
│    طلب إجراء لملفات القوالب المُخصّصة          │
│    إضافة الملفات الجديدة من الترقية            │
├─────────────────────────────────────────────────┤
│ 6. التحقق                                       │
│    تشغيل الاختبارات (forge test)               │
│    تشغيل التنسيق (forge lint)                  │
│    فحص صحة (forge doctor)                      │
│    تحديث forge.lock بالإصدار الجديد            │
└─────────────────────────────────────────────────┘

تصنيف الملفات

يُصنّف FORGE كل ملف مُولّد في إحدى ثلاث فئات، مما يُحدد كيف يتصرف أثناء الترقيات:

ملفات Core

ملفات تملكها أنت. لا يلمسها FORGE أبداً بعد التوليد الأولي.

apps/api/src/services/*.rs        # منطق أعمالك
apps/web/src/components/custom/   # مكوناتك المخصصة

يتتبع FORGE الـ checksum الأصلي لكن لا يُقارن أو يُحدّث هذه الملفات. أنت حر في تعديلها كيفما تشاء.

ملفات Managed

ملفات يملكها FORGE. تُحدّث تلقائياً أثناء الترقيات.

apps/api/src/routes/mod.rs        # تسجيل المسارات
apps/api/migrations/*.sql         # ترحيلات قاعدة البيانات (غير قابلة للتغيير)

الملفات المُدارة تتضمن تعليق رأس:

rust

// FORGE MANAGED - DO NOT EDIT
// هذا الملف مُولّد تلقائياً وسيُستبدل أثناء الترقيات.

تحذير

لا تُعدّل الملفات المُدارة يدوياً. ستُستبدل تغييراتك في الترقية التالية. إذا كنت تحتاج لتخصيص التوجيه أو أمور مُدارة أخرى، استخدم نقاط التمديد التي يوفرها FORGE (مثل ملفات المسارات المخصصة التي تُستورد من الموجّه المُدار).

ملفات Template

ملفات قد تحتاج دمج. FORGE ولّدها، لكنك ربما خصّصتها.

apps/web/src/app/layout.tsx       # ربما أضفت headers مخصصة
apps/admin/src/components/Sidebar.tsx  # ربما أضفت عناصر قائمة
docker-compose.yml                # ربما أضفت خدمات

يتتبع FORGE كلاً من الـ checksum الأصلي (عند التوليد) والـ checksum الحالي. أثناء الترقية:

إذا تطابقت الـ checksums (لم تُعدّلها): تحديث تلقائي آمن
إذا اختلفت الـ checksums (خصّصتها): طلب إجراء

التعامل مع الملفات المُخصّصة

عندما يُعدّل ملف قالب من قبلك والترقية تحتاج أيضاً تغييره، يعرض FORGE طلباً تفاعلياً:

┌─────────────────────────────────────────────────────────────────┐
│ apps/web/src/app/layout.tsx                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ - import { Inter } from 'next/font/google'                     │
│ + import { Inter, Cairo } from 'next/font/google'  // خط RTL  │
│                                                                 │
│   export default function RootLayout({ children }) {           │
│ -   return <html lang="en">                                    │
│ +   return <html lang={locale} dir={direction}>                │
│                                                                 │
│ تغييراتك:                                                       │
│ + أضفت مكون header مخصص في السطر 15                            │
│ + أضفت سكربت تحليلات في السطر 42                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

ماذا تريد أن تفعل؟
  [A] قبول الإصدار الجديد (ستُفقد تغييراتك)
  [K] الاحتفاظ بإصدارك (تخطي هذا التغيير)
  [M] الدمج (فتح في المحرر للدمج اليدوي)
  [D] عرض الفرق الكامل
  [S] تخطي الآن

هذا يضمن عدم فقدان العمل المخصص بدون موافقة صريحة.

أوامر الترقية

`forge upgrade:apply`

أمر الترقية الرئيسي:

bash

# الترقية إلى أحدث إصدار متوافق
forge upgrade:apply

# الترقية إلى إصدار محدد
forge upgrade:apply --version=2.1.0

# معاينة التغييرات بدون تطبيق
forge upgrade:apply --dry-run

# تخطي إنشاء نسخة احتياطية
forge upgrade:apply --no-backup

`forge upgrade:check`

التحقق من الترقيات المتاحة بدون إجراء تغييرات:

bash

forge upgrade:check

`forge upgrade:rollback`

التراجع عن آخر ترقية:

bash

# التراجع إلى الإصدار السابق
forge upgrade:rollback

# التراجع إلى إصدار محدد
forge upgrade:rollback --version=2.0.0

عملية التراجع:

استعادة forge.yaml و forge.lock من النسخة الاحتياطية
التراجع عن ترحيلات قاعدة البيانات المُضافة بالترقية
إرجاع تغييرات الكود باستخدام تاريخ git
التحقق من أن التطبيق لا يزال يجتاز الاختبارات

`forge upgrade:history`

عرض تاريخ الترقيات للمشروع:

bash

forge upgrade:history

المخرجات:

تاريخ الترقيات لـ myapp
─────────────────────────

الإصدار   التاريخ              النوع    الحالة
───────   ──────────────────   ──────   ──────
2.0.0     2026-01-15 10:00     أولي     نجاح
2.0.1     2026-01-18 14:30     patch    نجاح
2.1.0     2026-01-22 09:15     minor    نجاح

`forge doctor`

التحقق من صحة المشروع بعد الترقية:

bash

forge doctor

المخرجات:

FORGE Doctor - فحص صحة المشروع

  ✓ forge.yaml صالح
  ✓ سلامة forge.lock مُتحققة
  ✓ جميع الترحيلات مُطبّقة
  ✓ الخلفية تُترجم (cargo check)
  ✓ الواجهة الأمامية تُبنى (npm run build)
  ✓ عقد API مُلبّى
  ✓ الصفحات المطلوبة موجودة
  ✓ الصلاحيات مزروعة بشكل صحيح

جميع الفحوصات نجحت. المشروع سليم.

مثال ترقية Minor

ترقية إصدار minor نموذجية (بدون تغييرات كاسرة):

bash

$ forge upgrade:apply

جاري التحقق من التحديثات...
  الحالي: 2.0.0
  الأحدث:  2.1.0 (minor)

التغييرات في 2.1.0:
  + إضافة دعم لغات RTL
  + إضافة تحديد معدل طلبات مفاتيح API
  + تحسين سجل التدقيق
  + 1 ترحيل جديد

لا توجد تغييرات كاسرة.

المتابعة بالترقية؟ [Y/n] Y

جاري إنشاء نسخة احتياطية...          ✓
جاري تشغيل الترحيلات...              ✓
جاري تحديث الملفات المُدارة...        ✓
جاري تحديث forge.lock...             ✓

تمت الترقية بنجاح إلى 2.1.0

شغّل `forge test` للتحقق من أن كل شيء يعمل.

مثال ترقية Major

ترقية إصدار major مع تغييرات كاسرة تتطلب مزيداً من العناية:

bash

$ forge upgrade:apply --version=3.0.0

ترقية إصدار MAJOR

هذه الترقية تتضمن تغييرات كاسرة:
  - تغيّر تنسيق استجابة API
  - تغيّر تنسيق الصلاحيات (users.view → user:read)
  - إزالة أمر forge:ssl المُهمل

إجراءات يدوية مطلوبة بعد الترقية:
  1. تحديث استدعاءات API في الواجهة الأمامية للتنسيق الجديد
  2. تشغيل سكربت ترحيل الصلاحيات
  3. تحديث أي سكربتات تستخدم forge:ssl

اقرأ سجل التغييرات الكامل: https://forge.dev/changelog/3.0.0

المتابعة؟ [y/N] y

جاري إنشاء نسخة احتياطية...          ✓
جاري تشغيل فحوصات ما قبل الترقية...  ✓

الخطوة 1/5: ترحيل مخطط قاعدة البيانات
  جاري تشغيل 5 ترحيلات...            ✓

الخطوة 2/5: تحديث معالجات API
  12 ملف مُحدّث                       ✓

الخطوة 3/5: ترحيل الصلاحيات
  جاري تحويل 24 صلاحية...            ✓

الخطوة 4/5: تحديث الواجهة الأمامية
  3 ملفات تحتاج دمج يدوي

الخطوة 5/5: التحقق
  جاري تشغيل الاختبارات...           ✓
  جاري تشغيل التنسيق...              ✓

اكتملت الترقية إلى 3.0.0!

خطوات يدوية متبقية:
  - مراجعة ودمج 3 ملفات متعارضة
  - تحديث تكاملات API المخصصة (راجع دليل الترحيل)

أفضل الممارسات

الممارسة	السبب
دائماً انسخ احتياطياً أولاً	استخدم `forge upgrade:apply` (يُنشئ نسخة احتياطية افتراضياً) أو commit إلى git قبل الترقية
رقّي staging أولاً	اختبر الترقية على بيئة staging قبل الإنتاج
اقرأ سجل التغييرات	`forge upgrade:check` يُظهر ما تغيّر -- اقرأه
رقّي تدريجياً	اذهب 2.0 إلى 2.1 إلى 2.2 إلى 3.0، وليس 2.0 إلى 3.0 مباشرة
أضف forge.lock للتحكم بالإصدارات	احتفظ به في version control ليبقى الفريق كله متزامناً
شغّل الاختبارات بعد الترقية	`forge test && forge lint` تلتقط الانحدارات
تجنب تعديل الملفات المُدارة	الملفات المُعلّمة `FORGE MANAGED` ستُستبدل
شغّل `forge doctor`	فحص صحة ما بعد الترقية يلتقط المشاكل مبكراً

نصيحة

أكثر سير عمل ترقية آمناً: أضف جميع التغييرات إلى git، شغّل forge upgrade:apply، شغّل forge test، وإذا فشل أي شيء، استخدم git reset للعودة إلى حالة ما قبل الترقية. هذا يعطيك مسار تراجع نظيف مستقل عن آلية التراجع المُضمّنة في FORGE.

إدارة الإصدارات والترقيات ​

إصداران منفصلان ​

تتبع الإصدارات ​

forge.yaml ​

forge.lock ​

الإصدارات الدلالية ​

ما يُشكّل تغييراً كاسراً ​

التحقق من الترقيات ​

عملية الترقية ​

تصنيف الملفات ​

ملفات Core ​

ملفات Managed ​

ملفات Template ​

التعامل مع الملفات المُخصّصة ​

أوامر الترقية ​

forge upgrade:apply ​

forge upgrade:check ​

forge upgrade:rollback ​

forge upgrade:history ​

forge doctor ​

مثال ترقية Minor ​

مثال ترقية Major ​

أفضل الممارسات ​

إدارة الإصدارات والترقيات

إصداران منفصلان

تتبع الإصدارات

forge.yaml

forge.lock

الإصدارات الدلالية

ما يُشكّل تغييراً كاسراً

التحقق من الترقيات

عملية الترقية

تصنيف الملفات

ملفات Core

ملفات Managed

ملفات Template

التعامل مع الملفات المُخصّصة

أوامر الترقية

`forge upgrade:apply`

`forge upgrade:check`

`forge upgrade:rollback`

`forge upgrade:history`

`forge doctor`

مثال ترقية Minor

مثال ترقية Major

أفضل الممارسات