‏CI/CD لحزم 2GP: أتمتة بناء الحزم المفتوحة والمُدارة

الإجابة باختصار: خط أنابيب CI/CD لحزم 2GP ينشئ إصدار حزمة عند كل دمج، ويثبت هذا الإصدار في scratch org جديدة، ويشغل الاختبارات عليه، ثم يرقي ما ينجح فقط. خط الأنابيب نفسه خمسة أوامر. أما ما يكسر بناء 2GP بعد شهور فليس خط الأنابيب، بل قرارات النسب (ancestry) والـ namespace التي اتُخذت في الأسبوع الأول.

ماذا يفعل خط أنابيب 2GP فعليا؟

خمس مراحل بهذا الترتيب:

1. تحقق من المصدر. تحليل ساكن وفحص أسلوب على الـ pull request، قبل بناء أي شيء.
2. ابنِ إصدار حزمة. إصدار تجريبي مبني من المصدر، لا من مؤسسة.
3. ثبّته في بيئة نظيفة. الـ scratch org الجديدة تثبت أن الحزمة تُثبَّت فعلا، وهذا ادعاء مختلف عن "الكود يُنشر".
4. اختبر ضد الحزمة المثبتة. الكود داخل الـ namespace يتصرف بشكل مختلف بعد التحزيم، لذا تعمل الاختبارات بعد التثبيت.
5. ارقِ ما ينجح. الترقية هي البوابة، وهي الخطوة الوحيدة التي يجب أن يصعب تشغيلها.

الفرق المهم: نشر الميتاداتا يثبت أنها تُترجم داخل مؤسسة تملكها. أما تثبيت إصدار حزمة فيثبت أنها تعمل داخل مؤسسة لا تملكها.

ما الفرق بين الحزم المفتوحة وحزم 2GP المُدارة؟

• الحزم المفتوحة (unlocked) لمؤسساتك أو مؤسسات عميلك. لا namespace مطلوب، ولا نسب، ولا مراجعة أمنية. الإصدارات رخيصة وقابلة للاستبدال.
• حزم 2GP المُدارة للتوزيع: namespace مسجل، وحماية للملكية الفكرية، ونسب، ومسارات ترقية للمشتركين، ومراجعة أمنية على AppExchange.

شكل خط الأنابيب واحد في الحالتين. أما نتيجة الترقية الخاطئة فليست واحدة: الإصدار المفتوح الذي تندم عليه يمكن استبداله، والإصدار المُدار بعد ترقيته يصبح واجهة عامة إلى الأبد.

كيف تبني خط الأنابيب خطوة بخطوة؟

1. وثّق دخول الـ Dev Hub بلا تفاعل. عبر تدفق JWT bearer بشهادة محفوظة في مخزن أسرار الـ CI. ويجب أن يكون الـ Dev Hub هو المؤسسة المالكة للـ namespace، وإلا فشل إنشاء الإصدار فورا.
2. أنشئ الإصدار: sf package version create --package MyPackage --code-coverage --installation-key-bypass --wait 60، واحتفظ بمعرّف 04t الناتج كمخرج من خط الأنابيب.
3. شغّل scratch org: sf org create scratch --definition-file config/project-scratch-def.json --duration-days 1 --wait 10.
4. ثبّت واختبر: sf package install --package 04tXXXX --wait 20 ثم sf apex run test --test-level RunLocalTests --code-coverage --wait 30.
5. ارقِ على فرع الإصدار فقط: sf package version promote --package [email protected].

كل ما قبل الخطوة الخامسة يعمل على كل pull request. أما الخطوة الخامسة فتعمل على فرع واحد فقط، خلف موافقة بشرية.

كيف تضبط النسب والـ namespace حتى لا ينكسر البناء لاحقا؟

النسب (Ancestry)

النسب يخص حزم 2GP المُدارة فقط، وهو الموضع الذي تنحرف فيه خطوط الأنابيب الآلية بهدوء. سيلزفورس تشترط أن يكون السلف المحدد هو أعلى رقم إصدار مُرقّى للحزمة، وألا يُدرج كسلف إلا إصدار رُقّي إلى حالة managed-released (Salesforce Developers). ثلاث قواعد تضعها في خط أنابيبك:

• استخدم الكلمة المفتاحية. "ancestorVersion": "HIGHEST" في sfdx-project.json تضبط السلف تلقائيا على أعلى إصدار مُرقّى، وهو ما تحتاجه بيئة الـ CI بالضبط. والبدائل رقم major.minor.patch صريح أو ancestorId.
• لا ترقِّ بناء نجح نصف نجاح. الإصدار المُرقّى يصبح السلف التالي، فترقية الضجيج تورّثه لسلسلة النسب كلها.
• اعرف ثمن كسر السلسلة. يمكنك كسر الترقيم الخطي بـ --skip-ancestor-check، لكن الحزم لا تترقى إلا على امتداد سلسلة النسب، فأي مشترك على إصدار متروك يفقد مسار الترقية.

وللإصدارات التصحيحية قاعدة خاصة: لا يصلح الـ patch أن يكون سلفا مباشرا لإصدار غير تصحيحي.

الـ Namespace

• اربط الـ namespace بالـ Dev Hub الذي يسجل الـ CI الدخول إليه. هذا التعارض وحده أكثر أسباب فشل التشغيل الأول شيوعا.
• 2GP يسمح بعدة حزم داخل namespace واحد. افصل حسب مجلد الحزمة في sfdx-project.json، وصرّح بالاعتماديات بين الحزم صراحة مع أرقام إصداراتها.
• قادم من 1GP؟ سيلزفورس أتاحت Package Migrations بشكل عام في Summer '25: تحويل حزمة 1GP إلى 2GP بأمر sf package convert ونقل المشتركين المثبَّتين معها.

كيف تبقي خط أنابيب 2GP سريعا؟

• جهّز مخزونا من الـ scratch orgs. إنشاء المؤسسات عادة أبطأ من بناء الحزمة، والمؤسسات المسخّنة مسبقا تخرج هذه الخطوة من المسار الحرج.
• حدد نطاق الاختبارات لكل مرحلة. اختبارات ذات صلة على الـ pull request، وRunLocalTests قبل الترقية.
• خزّن الإصدار مؤقتا. إن لم يتغير المصدر فلا تعِد بناء الحزمة.

يمكنك تركيب ذلك كله من Salesforce CLI مع GitHub Actions أو Azure Pipelines أو CumulusCI. وSerpent يعطيك نفس خط الأنابيب بلا ملفات YAML: مسارات أصلية لحزم 1GP و2GP والحزم المُدارة، وحل الاعتماديات بين الحزم، وإدارة الإصدارات عبر مؤسسات المشتركين في كل الخطط، مع تجميع مسبق للـ scratch orgs في خطة Scale. تلاقي أدلة بناء وإصدار إضافية في SF Guides.

FAQ

هل يمكن أتمتة إنشاء حزم 2GP بالكامل؟

نعم. إنشاء الإصدار والتثبيت والاختبار والترقية كلها أوامر CLI، فتعمل الدورة كاملة بلا تدخل. ومع ذلك أبقِ الترقية خلف موافقة بشرية.

ما هو نسب الحزمة في 2GP؟

هو السلسلة المعلنة بين إصدارات الحزمة المُدارة. تحدد مسار الترقية للمشتركين، لأن الحزم لا تترقى إلا على امتداد هذه السلسلة.

هل تحتاج الحزم المفتوحة إلى namespace؟

لا. يمكن إنشاؤها بدونه، ولهذا تناسب المؤسسات الداخلية. أما 2GP المُدارة فتتطلب namespace مسجلا ومرتبطا بالـ Dev Hub.

لماذا يفشل إنشاء إصدار الحزمة بسبب النسب؟

غالبا لأن السلف المذكور ليس إصدارا مُرقّى بحالة managed-released، أو لأن إصدارا تصحيحيا وُضع سلفا لإصدار غير تصحيحي.

هل يرقّي الـ CI كل بناء ناجح؟

لا. الترقية غير قابلة للتراجع عمليا وتحدد السلف التالي، فمكانها فرع الإصدار خلف موافقة، لا كل عملية دمج.