حل الاعتماديات بين الحزم في سيلزفورس: التصميم وترتيب التثبيت والترقية الآمنة

الإجابة المختصرة: حل الاعتماديات بين الحزم هو الطريقة التي تحدد بها سيلزفورس أي الحزم يجب أن تكون موجودة مسبقا، وبأي إصدارات، قبل أن تُثبَّت حزمة أخرى أو تُرقّى. تعلن عن ذلك في مصفوفة dependencies داخل sfdx-project.json، مرتبة بترتيب التثبيت. لو ضبطت الترتيب والحدود الدنيا للإصدارات صارت ترقيات المشتركين مملة بالمعنى الجيد. ولو أخطأت فيها انتهت مؤسسة عميل إلى إصدار لا تستطيع مغادرته.

ما هي اعتمادية الحزم بالضبط؟

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

كيف تعلن عن اعتمادية بين حزمتين؟

داخل مدخل package directory في sfdx-project.json، بإحدى صيغتين:

• اسم مستعار يحمل الإصدار بالفعل: { "package": "[email protected]" }
• الحزمة والإصدار منفصلين: { "package": "MyPackage", "versionNumber": "1.0.0.RELEASED" }

وثلاث قواعد تزن أكثر من الصياغة نفسها.

• الترتيب هو ترتيب التثبيت. إذا كان للحزمة أكثر من اعتمادية، تُقرأ القائمة بوصفها التسلسل الواجب للتثبيت.
• الاعتماديات الدائرية غير مدعومة. أن تعتمد A على B بينما تعتمد B على A ليس لغزا يُحل، بل تصميم يجب تفكيكه.
• السلاسل متعددة المستويات مدعومة. يمكن أن تعتمد C على B وB على A. فعّل "calculateTransitiveDependencies": true لتعلن عن الاعتماديات المباشرة فقط بينما تُحسَب غير المباشرة نيابة عنك. وبدونه ستضطر لسرد كل مستوى بيدك إلى ما لا نهاية.

أي أنواع الحزم يمكن أن تعتمد على أي؟

هذا يقيّد البنية، فافحصه قبل أن ترسمها.

• الحزمة المُدارة 2GP يمكن أن تعتمد على حزمة مُدارة 2GP وعلى حزم unlocked.
• الحزمة المُدارة 2GP لا يمكن أن تعتمد على حزمة مُدارة 1GP. سيلزفورس تمنع تثبيت حزم 2GP المُدارة داخل مؤسسات تعبئة 1GP المُدارة. وإذا كان منتجك يحتاج ذلك فعلا فالطريق هو فتح حالة لدى دعم الشركاء في سيلزفورس لطلب استثناء فردي، لا حيلة داخل سكربت البناء.
• الحزمة المُدارة 1GP يمكن أن تعتمد على 1GP و2GP المُدارة وعلى حزم unlocked.
• اعتماد حزم unlocked على حزم مُدارة غير موصى به، ولا شيء مدعوم يعتمد على حزمة unmanaged.

وجود حزمة أساس 1GP تحت امتداد 2GP هو أكثر تصميم اعتمادي شيوعا يُضطر الفريق إلى التراجع عنه متأخرا، وهو مكلف عند تلك النقطة. اقرأ التركيبات المدعومة قبل أول بناء لا بعده.

كيف تصمم الحزم ليبقى الرسم البياني ضحلا؟

1. اتجاه واحد فقط. أساس، ثم ميزة، ثم طرف. وإذا أرادت حزمتان الإشارة لبعضهما فإن الـ metadata المشتركة مكانها حزمة ثالثة تحتهما.
2. الصغير المُجزّأ يتفوق على حزمة واحدة ضخمة. الإنشاء والتثبيت أسرع، واحتمال اصطدامك بالحدود أقل.
3. العمق هو البعد المكلف لا الاتساع. كل مستوى تضيفه يضاعف تنسيق الإصدارات: تغيير في القاع يستلزم إصدارا جديدا في كل مستوى فوقه قبل أن يرى المشترك شيئا.
4. ثبّت الإصدارات بوعي. رقم بناء مثبّت قابل لإعادة الإنتاج ومملّ بالمعنى الجيد. أما كلمة مثل RELEASED فتتبع آخر إصدار أطلقته، وهو أمر مريح أثناء التطوير ومفاجئ داخل بناء إصدار.

ما ترتيب التثبيت الصحيح داخل مؤسسة المشترك؟

1. ثبّت أو رقّ أولا أدنى حزمة في الرسم البياني، تلك التي لا اعتماديات لها.
2. اصعد مستوى بمستوى، حتى تجد كل حزمة شرطها المسبق محققا وقت تثبيتها.
3. ثبّت الحزمة الطرفية، أي التي اشتراها عميلك فعلا، في النهاية.
4. تحقق بدل أن تفترض. استعلام SOQL على SubscriberPackageVersion يخبرك بما هو مثبت في تلك المؤسسة وبأي إصدار، وهذا أفضل من قراءة صفحة Installed Packages والتمني.

ولو لم تستطع سرد هذا الترتيب لمنتجك أنت من الذاكرة، فلن يستطيعه فريق الدعم عندك في اللحظة التي يتعطل فيها عميل.

كيف تغيّر اعتمادية بدون أن تترك المشتركين عالقين؟

• الإصدار الجديد لا بد أن يكون سليلا مباشرا للإصدار المثبت. المشتركون لا يستطيعون تخطي السلسلة، فالحزمة التي انكسرت سلسلة أصلها هي حزمة لن تستطيع بعض المؤسسات ترقيتها.
• نسخ beta غير قابلة للترقية. المشترك الذي يحمل نسخة beta لا بد أن يزيلها قبل تثبيت نسخة released، وهذا في بيئة الإنتاج حديث عن فقدان بيانات. لا تترك أبدا نسخة beta داخل مؤسسة عميل.
• الـ metadata المحذوفة تُعلَّم كمهجورة أو تُحذف عند الترقية. نقل مكوّن من حزمة إلى أخرى هو حذف هنا وإضافة هناك، لذا فترتيب إصدار الحزمتين هو كل المخاطرة.
• ارفع الحد الأدنى للإصدارات درجة واحدة في كل مرة. قفز الإصدار المطلوب من حزمة الأساس عدة إصدارات دفعة واحدة يفرض سلسلة ترقيات على مشتركين لم يخططوا لأي منها.

التسلسل الذي ينجح عند تغيّر حزمة الأساس: أصدر نسخة الأساس، ثم انقل المشتركين إليها عبر نسخة موصى بها أو push upgrade، ثم أصدر الحزمة التابعة التي تشترطها. وعكس هاتين الخطوتين ينتج ترقية تفشل عند شرط مسبق داخل مؤسسة لا تراها ولا تستطيع إصلاحها من عندك.

ما الذي تؤتمته؟

1. ابنِ الرسم البياني من sfdx-project.json في كل تشغيلة لخط التسليم، وأفشل البناء عند اكتشاف دائرة.
2. ثبّت السلسلة كاملة في scratch org نظيفة بالترتيب المعلن في كل مرة، حتى تظهر أخطاء الترتيب وقت البناء لا داخل مؤسسة عميل.
3. سجّل الإصدارات المثبتة لكل مؤسسة مشتركة، ليجيب الدعم عن السؤال قبل أن يسأله للعميل.

Serpent يوفر حل الاعتماديات بين الحزم، ومسارات 1GP و2GP والحزم المُدارة، وإدارة النسخ عبر مؤسسات المشتركين في كل الخطط بما فيها المجانية. تجد أدلة تعبئة أخرى في مكتبة SF Guides عندنا.

FAQ

هل يمكن لحزمة 2GP مُدارة أن تعتمد على حزمة 1GP مُدارة؟

ليس افتراضيا. سيلزفورس تمنع هذه التركيبة، ويُطلب الاستثناء الفردي عبر فتح حالة لدى دعم الشركاء في سيلزفورس.

هل يلزمني سرد الاعتماديات غير المباشرة؟

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

ماذا يحدث لو اعتمدت حزمتان على بعضهما؟

لا شيء جيد، لأن الاعتماديات الدائرية غير مدعومة. استخرج الـ metadata المشتركة إلى حزمة أدنى تعتمد عليها الحزمتان.

أي حزمة أرقّيها أولا داخل مؤسسة المشترك؟

الأبعد إلى أسفل في الرسم البياني. الاعتماديات تسبق الحزم التي تحتاجها، وبنفس ترتيب التثبيت.

لماذا تفشل ترقية عميلي برسالة خطأ في الاعتماديات؟

غالبا بسبب الحد الأدنى للإصدار. حزمة الأساس المثبتة أقدم مما يشترطه إصدارك الجديد، فرقِّ حزمة الأساس أولا ثم أعد المحاولة.