سير عمل ترقية التبعيات الآمنة (Dependency Upgrade) — من مراجعة سجل التغييرات والتغييرات الكاسرة إلى الطرح التدريجي بترقية تبعية واحدة وبوابة اختبارات وخطة تراجع بإرجاع ملف القفل
سير عمل تنفيذي (runbook) يدير ترقية تبعية برمجية من أولها إلى آخرها بأمان: من جرد التبعية وتحديد إصدارها الهدف وسبب الترقية، مرورًا بمراجعة سجل التغييرات (CHANGELOG) ودليل الترحيل والتغييرات الكاسرة (Breaking Changes) ونشرات الأمان (Security Advisories / CVE)، ثم عزل الترقية والتكيّف مع الكسر واجتياز بوابة تحقق كاملة، وصولًا إلى الطرح التدريجي مع خطة تراجع فورية، ثم التنظيف والتوثيق. الهدف تحويل قرار «سأحدّث المكتبة» من مخاطرة عمياء (bump أعمى إلى الأحدث ثم انتظار الانفجار في الإنتاج) إلى عملية مقيسة تكشف الكسر مبكرًا وتُبقي التراجع في متناول اليد. يختلف هذا السير جوهريًا عن أصول قريبة في السوق ولا يكرّرها. أولًا هو ليس «مهارة ترقية الاعتماديات» الموجودة في فئة مهارات الوكلاء؛ تلك مهارة (SKILL.md) تضبط سلوك وكيل الكود عند الطلب وتذكّره بأن يبني الترقية على changelog/tests لا على bump أعمى — أي أداة توجيه للوكيل. بينما هذا سير عمل عملياتي كامل يديره مهندس أو فريق إصدار خطوةً بخطوة، ويضيف ما لا تغطّيه تلك المهارة: الطرح التدريجي للتبعية بعد الترقية، وبوابة قرار كمية على الاختبارات والبناء والـ audit، وخطة تراجع صريحة بإرجاع ملف القفل، وفترة تثبيت (soak)، وتنظيف المسار القديم والدين. وثانيًا هو ليس «سير النشر بإطلاق تدريجي (Canary)»؛ ذاك يوجّه حصة من حركة الإنتاج إلى بناء مَنشور جديد ويتراجع عند تدهور الصحة، بينما هذا يرقّي مكتبة/حزمة داخل الكود ويحكم على سلامتها ببوابة اختبارات وبناء وفحص أمني قبل الدمج، وتراجعه بإرجاع ملف القفل لا بتحويل حركة. وثالثًا هو ليس «سير دورة حياة أعلام الميزات» (مفتاح تشغيل زمن-تشغيل) ولا «سير ترحيل قاعدة البيانات» (تغيير مخطط) ولا «سير تدوير الأسرار» — بل هدفه المحدّد: استبدال إصدار تبعية بإصدار أحدث دون كسر الإنتاج، بالتعامل الصريح مع التغييرات الكاسرة ونشرات الأمان. يميّز السير أنواع الترقية لأن مخاطرها ومسارها يختلفان وفق الإصدار الدلالي (Semantic Versioning): ترقية patch (إصلاحات متوافقة خلفيًا، مخاطرة أدنى)، وترقية minor (إضافات متوافقة عادةً)، وترقية major (تغييرات كاسرة متوقعة تتطلب تكيّف الكود ودليل ترحيل)، وترقيع أمني (قد يكون patch لكنه عاجل بأولوية أعلى). فلا يُعامَل رفع رقم صغير كرفع إصدار كبير، ولا يُؤجَّل ترقيع ثغرة حرجة بحجة أنه «مجرد تحديث». يعمل السير عبر سبع مراحل: (1) الجرد وتحديد الهدف: ما التبعية، وإصدارها الحالي والهدف، ونوع الترقية وسببها (أمان/ميزة/دعم منتهٍ)، ومدى انتشارها في الكود. (2) مراجعة سجل التغييرات والتغييرات الكاسرة ونشرات الأمان بين الإصدار الحالي والهدف: اقرأ CHANGELOG ودليل الترحيل (Migration Guide) وملاحظات الإصدار وتنبيهات CVE، وسجّل التغييرات الكاسرة والـ deprecations وتغيّرات التبعيات النظيرة (peer dependencies) — هذه هي الخطوة التي يقفز فوقها الـ bump الأعمى. (3) عزل التغيير: فرع مخصّص، وترقية تبعية واحدة فقط (أو مجموعة مترابطة فعلًا)، وتثبيت الإصدار في ملف القفل (lockfile) بدل نطاق فضفاض يجلب إصدارًا غير مُختبَر. (4) التكيّف مع الكسر: عدّل الكود المتأثر بالواجهات المحذوفة أو المتغيّرة، وطبّق codemods الرسمية إن وُجدت، وحدّث peer dependencies، وأصلح التحذيرات. (5) بوابة التحقق: شغّل مجموعة الاختبارات الكاملة + فحص الأنواع (type check) + البناء (build) + التحقق الأمني (audit)؛ لا تمرّ عند فشل أي بوابة. (6) الطرح التدريجي مع خطة تراجع: انشر إلى staging ثم الإنتاج تدريجيًا مع مراقبة الأخطاء والأداء، وخطة التراجع جاهزة قبل النشر = إرجاع ملف القفل إلى الإصدار السابق. (7) التنظيف والتوثيق: أزِل رقع التوافق المؤقتة، وحدّث الوثائق، وسجّل الإصدار الجديد وسبب الترقية ونتيجة الـ audit، وأغلق التحذير الأمني. تحكمه قواعد صارمة: اقرأ سجل التغييرات ودليل الترحيل ونشرات الأمان قبل أي تعديل؛ رقِّ تبعية واحدة لكل تغيير ولا تخلط ترقيات غير مرتبطة تُصعّب التشخيص؛ ثبّت الإصدارات في ملف القفل ولا تعتمد نطاقًا فضفاضًا؛ لا ترقِّ إلى الأحدث عمياءً بل اختر الإصدار المستقر المناسب وافهم أثره؛ لا تمرّ ببناء أو اختبار فاشل أو تحذير كاسر؛ جهّز خطة تراجع (إرجاع ملف القفل) قبل النشر؛ ميّز patch/minor عن major وعامل كلًّا بحسبه؛ ولا تخترع رقم إصدار أو CVE أو نتيجة اختبار غير محقّقة. مناسب لمهندسي البرمجيات وDevOps وقادة الإصدار الذين يرقّون أطر عمل ومكتبات وحزمًا ويريدون إغلاق ثغرات أمنية دون كسر الإنتاج، ويعمل مع npm وpnpm وYarn وpip وPoetry وCargo وGo modules وMaven/Gradle، وقابل للتحويل إلى runbook أو checklist داخل Claude Code وCursor وCodex.
تقرير ترقية تبعية عربي منظّم وقابل للتطبيق: بطاقة الترقية (التبعية، الحالي ← الهدف، نوع الترقية وفق SemVer، السبب، مدى الانتشار)، مراجعة للتغييرات الكاسرة والـ deprecations وتغيّرات peer deps ونشرات الأمان بين الإصدارين، خطة عزل وتكيّف (فرع، تبعية واحدة، تثبيت في ملف القفل، وتعديلات الكود كـ diff)، بوابة تحقق كاملة (اختبارات + أنواع + بناء + audit) بشرط مرور صريح، خطة طرح تدريجي (staging ← إنتاج) مع خطة تراجع فورية بإرجاع ملف القفل، ثم تنظيف وتوثيق للإصدار الجديد وسبب الترقية ونتيجة الـ audit — كله مبني على قراءة التغييرات قبل التعديل، وترقية تبعية واحدة، وتثبيت في ملف القفل، ودون ترقية عمياء أو تجاوز بوابة فاشلة أو اختراع أرقام إصدار أو CVE.
