ترقية إصدارات التبعيات

تتيح لك ترقية التبعيات الاستفادة من أحدث الميزات وإصلاحات الأخطاء والتحسينات. لترقية تبعياتك، تحتاج إلى فهم كيفية حل Gradle للإصدارات التي تطلبها، والمخاطر التي ينطوي عليها، والخطوات التي يمكنك اتخاذها للتخفيف من هذه المخاطر.

راجِع استراتيجية الترقية

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

إنشاء مكتبة

هل تنشئ تطبيقًا يتم تنزيله وتشغيله على جهاز؟ أم أنك تنشئ مكتبة لمساعدة المطورين الآخرين في إنشاء تطبيقاتهم؟

إذا كنت بصدد إنشاء تطبيق، يجب أن تركّز على إبقاء تطبيقك محدّثًا ومستقرًا.

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

أولاً، عليك تقليل التبعيات في مكتبتك قدر الإمكان. وكلما قلّ عدد التبعيات، قلّ التأثير في حلّ التبعيات لدى المستخدِم.

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

ننصحك بإنشاء إصدار تجريبي من مكتبتك ليختبره المستخدمون في مرحلة مبكرة.

اطّلِع على إرشادات التوافق مع الإصدارات القديمة لمؤلفي المكتبات لمعرفة تفاصيل حول الحفاظ على توافق واجهة التطبيق الثنائية (ABI) في مكتبتك. استخدِم اختبارات الدمج والأدوات، مثل أداة التحقّق من التوافق الثنائي، للتأكّد من أنّ تغييرات ABI تتطابق مع التغيير المقصود في الإصدار.

إذا طرحت إصلاحات في patch على إصدارات أقل من مكتبتك، لن يحتاج المستهلكون إلى ترقية مكتبتك إلى الإصدار التالي من major أو minor إلا إذا كانوا يريدون الحصول على ميزات جديدة. تجنَّب ترقية التبعيات الانتقالية في هذه الترقيات.

إذا كانت ترقية مكتبتك تتطلّب إجراء تغييرات جذرية قد تكون صعبة على المستخدمين، ننصحك بإصدارها كعنصر جديد حتى يمكن للإصدارَين القديم والجديد التعايش معًا والسماح بطرح تدريجي أكثر.

ملاحظة: إذا كانت عملية الترقية لواحدة من التبعيات تتضمّن تغييرًا كبيرًا في واجهة برمجة التطبيقات، من المحتمل أن تحتاج إلى ترقيتها في إصدار major أو minor وإجراء أي تغييرات ضرورية. وفي حال عدم إجراء ذلك، قد يفعل مستخدمو مكتبتك ذلك، ما يؤدي إلى حدوث حالات عدم توافق بين مكتبتك والمورد التابع. وقد ينطبق ذلك حتى في حال عدم إجراء أي تغيير على مكتبتك. يمكنك إصدار نسخة جديدة فقط لترقية هذا المكوّن الإضافي.

دورة الإصدار

كم مرة تُصدر تطبيقك أو مكتبتك؟

دورات تطوير وإصدار أقصر

  • حان وقت الترقية.
  • يمكنك بسرعة أن تتأخر عن الموعد.
  • يمكن أن تُخفِّف الترقيات الصغيرة المتكرّرة من عبء العمل.
  • إذا تسبّبت ترقية المكتبة في حدوث مشكلة، يمكنك إلغاء هذه الترقية بسرعة أكبر.
  • تعمل أدوات مثل Dependabot وRenovate على تقليل حجم العمل، ولكن احرص على تحليل النتائج للتحقّق من المخاطر.

دورات تطوير وإصدار أطول

  • يتوفّر المزيد من الوقت لإجراء الترقيات واختبارها.
  • من المرجّح أن يتم إصدار إصدارات أحدث من التبعيات خلال دورتك.
  • يستغرق التراجع عن الترقيات وطرح تطبيقك أو مكتبتك وقتًا أطول.

الاطّلاع على أحدث الميزات

هل تفضّل استخدام أحدث الميزات وواجهات برمجة التطبيقات المتاحة، أم أنّك تُجري الترقية فقط عندما تحتاج إلى ميزة أو إصلاح خطأ؟

ننصحك بالتفكير في المفاضلات بين الترقيات المتكرّرة. تكون الترقيات المستقبلية أسهل (عدد التغييرات المطلوب دمجها أقل)، ولكنك تواجه مخاطر الترقية بشكلٍ متكرّر.

يمكن أن يساعد اختبار الترقيات إلى الإصدارات التجريبية (الإصدارات ألفا والإصدارات التجريبية والإصدارات المرشحة للإصدار) من المكتبات في الاستعداد عند توفّر الإصدارات الثابتة.

تبعية جديدة

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

فريق مخصّص

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

نوع الترقية

تكون بعض الترقيات أكثر أهمية من غيرها. فكِّر في النقاط الأكثر أهمية بالنسبة إليك.

عادةً ما يكون لترقيات أدوات الإنشاء، مثل مكونات Gradle الإضافية وGradle الإضافية، تأثير أقل على المستخدمين، كما أن الكثير من المخاطر داخلية في تصميمك. ويساعد الإصدار نفسه في التحقّق من هذه التغييرات. من الصعب التحقّق من ترقيات المكتبات وحِزم تطوير البرامج (SDK)، كما أنّها تشكّل خطرًا أكبر على المستخدمين.

المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP): هي الأدوات المستخدَمة لإنشاء تطبيق Android أو مكتبته. هذه هي الترقية الأكثر أهمية التي يمكنك إجراؤها، إذ غالبًا ما تتضمّن أو تتيح تحسينات في الأداء وإصلاحات للأخطاء وقواعد جديدة في Lint ودعم للإصدارات الجديدة من نظام Android الأساسي.

Gradle: عليك غالبًا ترقية Gradle عند ترقية AGP أو مكوّن إضافي آخر من Gradle.

مكوّنات Gradle الإضافية الأخرى: تتغيّر أحيانًا واجهة برمجة التطبيقات الخاصة بالمكوّن الإضافي لنظام Gradle. عند ترقية Gradle، تحقّق من توفّر ترقيات للمكوّنات الإضافية التي تستخدمها.

Kotlin وJava: تتطلّب بعض المكتبات والمكوّنات الإضافية الحد الأدنى من إصدارات Kotlin أو Java، أو تريد الاستفادة من ميزات اللغة الجديدة أو واجهات برمجة التطبيقات أو تحسينات الأداء.

نظام التشغيل Android: يتطلّب "متجر Play" ترقيات منتظمة لحزمة تطوير البرامج (SDK) لنظام التشغيل Android. يجب اختبار الإصدارات الجديدة من حزمة تطوير البرامج (SDK) لنظام التشغيل Android في أقرب وقت ممكن. تتطلب بعض ترقيات حزمة تطوير البرامج (SDK) إجراء تغييرات على تطبيقك، مثل الأذونات الجديدة أو استخدام واجهات برمجة تطبيقات جديدة.

المكتبات — هل تريد تحديد أولويات المكتبات استنادًا إلى قُربها من البنية الأساسية؟

  • غالبًا ما تتغير المكتبات ذات الصلة بالأنظمة الأساسية والبنية، مثل AndroidX، للاستفادة من الميزات الجديدة أو المساعدة في إجراء تغييرات مجردة في النظام الأساسي. عليك ترقية هذه المكتبات على الأقل عند ترقية نظام Android الأساسي أو المكتبات الأخرى ذات الصلة بالبنية.
  • يمكن أن تتم زيادة ترقيات المكتبة الأخرى أو تأخيرها إلا إذا كنت بحاجة إلى ميزة جديدة أو إصلاحات أخطاء معيّنة.

استوديو Android: يتيح لك استخدام أحدث إصدار من "استوديو Android" الاستفادة من أحدث الميزات وإصلاحات الأخطاء في نظام IntelliJ IDEA الأساسي وأدواته للعمل مع أحدث حِزم تطوير البرامج (SDK) لنظام التشغيل Android.

الأدوات المتاحة

هناك العديد من الأدوات والمكوّنات الإضافية المتاحة لمساعدتك في الترقيات. تعمل أدوات مثل Dependabot وRenovate على ترقية إصدارات المكتبة في الإصدار تلقائيًا، ولكن احرص على تحليل النتائج للتحقّق من المخاطر.

استراتيجيات لأنواع محدّدة من الترقيات

قد تؤدي ترقية بعض أنواع التبعيات إلى تأثير متسلسل، ما يتطلّب ترقية أنواع أخرى من التبعيات. نناقش العلاقات بين عناصر الإنشاء في التبعيات المتبادلة بين الأدوات والمكتبة.

بناء التبعيات وعلاقاتها
الشكل 1. بناء العلاقات

عند ترقية كل نوع من أنواع المكوّنات، ضع في اعتبارك كيفية تأثير الترقية في المكوّنات الأخرى في الإصدار.

المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)

يتضمن "استوديو Android" مساعد ترقية AGP يمكنه المساعدة في هذه المهام.

في حال استخدام المساعد أو إجراء الترقية يدويًا، يُرجى مراعاة ما يلي:

اطّلِع على ملاحظات إصدار "مجموعة تطوير البرامج (AGP)".

عليك ترقية Gradle إلى الإصدار المدرَج على الأقل.

ترقية Android Studio إلى إصدار متوافق مع إصدار AGP الذي تم اختياره

استخدِم إصدارات "استوديو Android" وAGP التي تتوافق مع حزمة تطوير البرامج (SDK) لنظام التشغيل Android التي تريد استخدامها.

تحقَّق من التوافق مع أدوات إنشاء حِزم SDK ومجموعة تطوير البرامج (NDK) وJDK.

إذا كنت تُطوّر مكوّنًا إضافيًا في Gradle (للاستخدام الداخلي أو العام) يمدّد بيانات AGP أو يستخدمها، تحقّق ممّا إذا كنت بحاجة إلى ترقية المكوّن الإضافي. في بعض الأحيان، يوقف AGP واجهات برمجة التطبيقات نهائيًا ويزيلها لاحقًا، ما يؤدي إلى حدوث مشاكل في التوافق مع المكوّنات الإضافية السابقة.

المحول البرمجي للغة Kotlin واللغة وبيئة التشغيل

اطّلِع على ملاحظات إصدار Kotlin لمعرفة المشاكل المعروفة وحالات عدم التوافق.

إذا كنت تستخدم Jetpack Compose:

إذا كنت تستخدم معالجة رموز Kotlin (KSP)، يمكنك الاطلاع على KSP Quickstart للإعداد وإصدارات KSP للإصدارات المتاحة. يُرجى العِلم أنّه يجب استخدام إصدار من KSP يتطابق مع إصدار Kotlin. على سبيل المثال، إذا كنت تستخدم Kotlin 2.0.21، يمكنك استخدام أي إصدار من المكوّن الإضافي KSP يبدأ بالرقم 2.0.21، مثل 2.0.21-1.0.25. لن تحتاج عادةً إلى ترقية معالجات KSP (مثل مُجمِّع Room الذي يظهر كتبعية ksp في ملفات الإنشاء)، لأنّ المكوّن الإضافي KSP يلخّص الكثير من واجهة برمجة التطبيقات للمجمِّع، وواجهة برمجة التطبيقات KSP التي تستخدمها المعالجات مستقرة.

يمكنك ترقية جميع المكوّنات الإضافية الأخرى التي تستخدمها في برنامج Kotlin Compiler. غالبًا ما تتغير واجهة برمجة تطبيقات Kotlin Compiler Plugin API بين الإصدارات، ويجب أن تستخدم المكونات الإضافية واجهة برمجة تطبيقات متوافقة. إذا كان المكوّن الإضافي مُدرَجًا في مكوّنات المكوّن الإضافي للمجمّع، يجب استخدام الإصدار نفسه المستخدَم في مجمّع Kotlin. بالنسبة إلى أيّ مكونات إضافية أخرى للترجمة، راجِع مستنداتها للتعرّف على عملية الربط المناسبة.

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

أخيرًا، في بعض الحالات، تتغير لغة Kotlin، مما يتطلب منك تحديث التعليمات البرمجية. ويحدث ذلك غالبًا إذا كنت تختبر ميزات تجريبية. إذا لم يتم إنشاء الرمز البرمجي بشكل صحيح بعد ترقية مترجم Kotlin، تحقّق من التغييرات في اللغة أو حدوث خلل في مكتبة وقت التشغيل في ملاحظات إصدار Kotlin.

المكوّنات الإضافية لبرنامج ترميز Kotlin

إذا كنت بحاجة إلى ترقية المكون الإضافي لبرنامج تجميع Kotlin، يلزمك الترقية إلى الإصدار المطابق المستخدم من لغة Kotlin.

تستخدم معظم المكونات الإضافية لبرامج التحويل البرمجي بلغة Kotlin الإصدار نفسه مثل المحول البرمجي لـ Kotlin، أو تبدأ بالإصدار المطلوب من برنامج التحويل البرمجي بلغة Kotlin. على سبيل المثال، إذا كان إصدار المكوِّن الإضافي هو 2.0.21-1.0.25، فيجب استخدام الإصدار 2.0.21 من برنامج التجميع بلغة Kotlin.

يتطلّب تغيير إصدار مترجم Kotlin أحيانًا إجراء تغييرات أخرى.

المكتبات

المكتبات هي العناصر الأكثر ترقيةً في عملية الإنشاء. ستظهر لك الترقيات المتاحة في محرِّر "استوديو Android"، أو إذا كنت تستخدم بعض أدوات التبعيات والمكونات الإضافية.

تحدِّد بعض المكتبات الحدّ الأدنى من compileSdk أو minSdk المطلوب لاستخدام المكتبة. إذا لم تستخدم compileSdk المحدّد على الأقل، ستتعذّر عمليات الإنشاء. ومع ذلك، يتم ضبط minSdk لتطبيقك تلقائيًا على الحد الأقصى لجميع قيم minSdk المحدّدة في ملفات الإنشاء وملحقات المكتبة.

وتحدِّد بعض المكتبات أيضًا الحد الأدنى لإصدار Kotlin المطلوب استخدامه. عدِّل إصدار Kotlin في ملفات الإنشاء ليكون على الأقل الإصدار المحدّد.

Gradle

أحيانًا تُوقِف الإصدارات الجديدة من Gradle واجهات برمجة التطبيقات الحالية، وتزيل هذه الواجهات في إصدار مستقبلي. إذا كنت تُطوّر مكوّنًا إضافيًا لـ Gradle، عليك ترقيته في أقرب وقت ممكن، خاصةً إذا كان هذا المكوّن الإضافي متاحًا للجميع.

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

لترقية Gradle:

  • اقرأ ملاحظات الإصدار الخاصة بالإصدار الذي تريد استخدامه.
  • ترقية إصدار Gradle في gradle/wrapper/gradle-wrapper.properties
  • عليك ترقية حزمة Gradle wrapper jar والنصوص البرمجية من خلال تشغيل ./gradlew wrapper --gradle-version latest.
  • ترقية مكوّنات Gradle الإضافية
  • ترقية JDK المُستخدَم لتشغيل Gradle

مكوّنات Gradle الإضافية

أحيانًا تستخدم مكونات Gradle التي تمت ترقيتها واجهات برمجة تطبيقات Gradle الجديدة أو التي تم تغييرها، والتي تتطلب بدوره ترقية Gradle أو ربما تغييرات في تهيئتها في ملفات التصميم. وفي كلتا الحالتَين، ستظهر لك تحذيرات أو أخطاء بشأن عملية الإنشاء للإشارة إلى عدم التوافق.

عند ترقية المكوّنات الإضافية، عليك ترقية Gradle.

حزمة تطوير البرامج (SDK) لنظام التشغيل Android

يحتوي "استوديو Android" على مساعد ترقية حزمة تطوير البرامج (SDK) لنظام التشغيل Android يمكنه المساعدة في هذه المهام.

في حال استخدام المساعد أو إجراء الترقية يدويًا، يُرجى مراعاة ما يلي:

يحتوي كل إصدار من حزمة تطوير البرامج (SDK) لنظام التشغيل Android على ميزات وواجهات برمجة تطبيقات جديدة وإصلاحات للأخطاء وتغييرات في السلوك. يتطلّب "متجر Play" تحديث targetSdk، ولكن ننصحك بتحديث targetSdk قبل الموعد النهائي لكي يكون لديك وقت إضافي لإجراء أي تغييرات ضرورية.

قبل ترقية حزمة تطوير البرامج (SDK) لنظام التشغيل Android، يُرجى قراءة ملاحظات الإصدار بعناية. انتبه جيدًا لقسم تغييرات السلوك، الذي يتضمن:

  • الأذونات الجديدة التي يجب طلبها عند التثبيت أو وقت التشغيل
  • واجهات برمجة التطبيقات التي تم إيقافها نهائيًا وبدائل لها
  • التغييرات الأساسية في واجهات برمجة التطبيقات أو السلوك
  • واجهات برمجة تطبيقات Kotlin أو Java الجديدة، والتي قد تؤثر في رمزك البرمجي

يمكن أن يكون قسم "تغييرات السلوك" طويلاً جدًا، ولكن عليك الانتباه إليه جيدًا لأنّه غالبًا ما يحتوي على تغييرات مهمة عليك إجراؤها على تطبيقك.

يجب ترقية targetSdk لاستيفاء متطلبات "متجر Play". ترقية compileSdk اختيارية، ما يتيح لك الوصول إلى واجهات برمجة تطبيقات جديدة. تجدر الإشارة إلى أنّ بعض المكتبات، مثل AndroidX، تتضمن حدًا أدنى لمتطلبات compileSdk.

للاستفادة من ميزات حزمة SDK الجديدة أثناء التطوير وضمان التوافق أثناء عملية الإنشاء، عليك ترقية المكوّن الإضافي Android Gradle (AGP) و"استوديو Android". وتشمل هذه الأدوات أدوات جديدة ومحسّنة لحِزم SDK الجديدة. الاطّلاع على الحد الأدنى من إصدارات الأدوات لمستوى واجهة برمجة تطبيقات Android

عند ترقية حزمة تطوير البرامج (SDK) لنظام التشغيل Android، يجب ترقية أي مكتبات AndroidX تستخدمها. غالبًا ما يستخدم AndroidX واجهات برمجة التطبيقات الجديدة والمحدّثة لتحسين التوافق والأداء عبر إصدارات Android SDK.

Android Studio

يمكنك بشكل عام ترقية "استوديو Android" في أي وقت. قد تظهر لك رسائل تطلب منك ترقية AGP أو ترقية حزمة تطوير البرامج (SDK) لنظام التشغيل Android. ننصح بشدة بإجراء هذه الترقيات، ولكنها ليست مطلوبة.

إذا أردت لاحقًا استخدام "استوديو Android" لترقية AGP أو حزمة تطوير البرامج (SDK) لنظام التشغيل Android، يمكنك العثور على هذين الخيارَين في قائمة الأدوات:

Java

إذا كان لديك رمز مصدر Java في تطبيق Android، ننصحك بالاستفادة من واجهات برمجة تطبيقات Java الأحدث.

يتوافق كل إصدار من حزمة تطوير البرامج (SDK) لنظام التشغيل Android مع مجموعة فرعية من واجهات برمجة تطبيقات Java وميزات اللغة. يوفر AGP التوافق مع الإصدارات الأقدم من حزمة تطوير البرامج (SDK) لنظام التشغيل Android باستخدام عملية تُسمى إزالة التوافق.

تحدِّد ملاحظات الإصدار لحزمة تطوير البرامج (SDK) لنظام التشغيل Android مستوى Java المتوافق والمشاكل المحتمَلة. قد تؤثر بعض هذه المشاكل في رمز Kotlin المصدر أيضًا، لأنّ لغة Kotlin يمكنها الوصول إلى واجهات برمجة تطبيقات Java نفسها. احرص على الانتباه جيدًا إلى أقسام JDK API التي تظهر في قسم "التغييرات السلوكية" ضمن ملاحظات الإصدار، حتى إذا لم يكن لديك رمز مصدر Java.

يتم تحديد استخدام حزمة JDK في عدة مواضع في نصوص إنشاء البرامج. اطّلِع على إصدارات Java في إصدار Android للحصول على مزيد من المعلومات.

تحليل الترقية

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

  • هل تريد تغيير الرمز البرمجي بسبب تغييرات واجهة برمجة التطبيقات؟
  • هل تريد إضافة عمليات تحقّق جديدة من الأذونات؟
  • هل تريد إنشاء اختبارات إضافية أو تعديل الاختبارات الحالية لرصد التغييرات في السلوك؟

يُرجى العِلم أنّ التبعيات التي تمت ترقيتها قد تؤدي إلى ترقية إصدارات التبعيات التي تعتمد عليها. ويمكن أن يؤدي ذلك بسرعة إلى مجموعة هائلة من التغييرات.

إذا كنت تستخدم أداة مثل Renovate أو Dependabot لتشغيل عمليات الترقية تلقائيًا، يُرجى العِلم أنّ هذه الأدوات لا تُجري أي تحليل نيابةً عنك، بل تُجري الترقية إلى أحدث إصدارات المكتبة. لاتفترض أنّ كل شيء سيعمل بشكل صحيح بعد هذه الأنواع من الترقيات التلقائية.

إنّ مفتاح عمليات الترقية الناجحة هو تحليل الترقية:

  1. تحديد الاختلافات في التبعيات قبل الترقيات وبعدها
  2. راجِع كل تغيير وحدِّد المخاطر المعنيّة.
  3. الحدّ من المخاطر أو قبول التغييرات أو رفضها

تحديد أوجه الاختلاف في التبعية

الخطوة الأولى في تحليل الترقية هي تحديد كيفية تغيُّر التبعيات. يمكنك الاستفادة من نظام التحكّم في الإصدارات (VCS، مثل Git) والمكوّن الإضافي Dependency Guard للاطّلاع على التغييرات بسرعة. هدفك هو إنشاء لقطة قبل وبعد الإجراء ومقارنة كلتا اللقطتَين.

إعداد وإنشاء أول مرجع لك

قبل بدء عملية الترقية، تأكّد من إنشاء مشروعك بنجاح.

من الأفضل حلّ أكبر عدد ممكن من التحذيرات أو إنشاء أسس لمتابعة التحذيرات التي سبق لك رؤيتها.

  • أداة Lint: يمكنك فحص تحذيرات أداة Lint الحالية وإنشاء مرجع Android Lint.
  • مُجمِّع Kotlin:
  • الأدوات الأخرى: إذا كنت تستخدم أدوات تحليل ثابتة أخرى (مثل Detekt) تتيح تتبُّع قاعدة بيانات مرجعية، عليك إعداد قاعدتها المرجعية.

تسهِّل قواعد التحذيرات الأساسية هذه الاطّلاع على التحذيرات الجديدة التي يتم تقديمها أثناء ترقية التبعيات.

إنشاء أساس تبعية من خلال إعداد واقي التبعية وتشغيله في كتالوج إصدار Gradle/libs.versions.toml، أضف:

[versions]
dependencyGuard = "0.5.0"

[plugins]
dependency-guard = { id = "com.dropbox.dependency-guard", version.ref = "dependencyGuard" }

وأضِف ما يلي إلى ملف إنشاء تطبيقك:

Kotlin

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration("releaseRuntimeClasspath")
}

رائع

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration('releaseRuntimeClasspath')
}

إنّ إعدادات releaseRuntimeClasspath هي هدف محتمل، ولكن إذا أردت استخدام إعدادات مختلفة، يمكنك تشغيل ./gradlew dependencyGuard بدون إعدادات مُدرَجة في ملف الإنشاء للاطّلاع على جميع الإعدادات المتاحة.

بعد الإعداد، يمكنك تشغيل ./gradlew dependencyGuard لإنشاء تقرير في app/dependencies/releaseRuntimeClasspath.txt. هذا هو تقريرك الأساسي. احفظ هذا التغيير في نظام التحكّم في الإصدارات (VCS).

يُرجى العِلم أنّ أداة Dependency Guard لا تسجِّل سوى قائمة تبعيات مكتبة. هناك ملحقَان آخران في ملفات الإنشاء، مثل إصدارَي Android SDK وJDK. يسمح الالتزام بـ VCS قبل تغييرات التبعية لفرق VCS بتسليط الضوء على هذه التغييرات أيضًا.

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

بعد الحصول على مرجع، عليك ترقية التبعيات وتغييرات التصميم الأخرى التي تريد اختبارها. لا تُعدِّل رمز المصدر أو الموارد في هذه المرحلة.

يمكنك تشغيل ./gradlew lint للاطّلاع على تحذيرات أو أخطاء جديدة في أداة فحص الأخطاء. عليك معالجة أيّ مشاكل مهمّة ثم تعديل مستوى التحذير الأساسي من خلال تشغيل ./gradlew lint -Dlint.baselines.continue=true. إذا استخدمت أدوات أخرى لتسجيل نقاط مرجعية للتحذير، مثل Kotlin WARNING Baseline أو Kotlin WARNINGs Baseline Builder، ننصحك بمعالجة التحذيرات الجديدة وتعديل الأسس أيضًا.

شغِّل ./gradlew dependencyGuard لتعديل تقرير "الأداء الأساسي". بعد ذلك، يمكنك تشغيل مقارنة CVS لعرض التغييرات التي لا تخصّ المكتبة. من المحتمل أن تتضمّن عملية الترقية العديد من عمليات الترقية التي تخصّ مكتبتك والتي لم تكن تتوقّعها.

تحليل المخاطر

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

في ما يلي بعض النقاط التي يجب مراعاتها:

تحديثات الإصدارات الرئيسية

هل تغيّر رقم الإصدار الرئيسي؟

في الإصدار الدلالي، يُعرف الرقم الأول باسم رقم الإصدار الرئيسي. على سبيل المثال، إذا تم ترقية إصدار مكتبة من 1.2.3 إلى 2.0.1، يعني ذلك أنّه تم تغيير الإصدار الرئيسي. يشير ذلك عادةً إلى أنّ مطوّر المكتبة أجرى تغييرات غير متوافقة بين الإصدارات، مثل إزالة أجزاء من واجهة برمجة التطبيقات أو تغييرها.

عند ظهور هذا الرمز، يجب الانتباه بشكل خاص إلى المكتبات المتأثرة عند النظر في أيّ من الاعتبارات التالية.

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

واجهة برمجة تطبيقات غير مستقرة

قد تتضمن بعض إصدارات المكتبة واجهات برمجة تطبيقات غير مستقرة. وعادةً ما تكون هذه واجهات برمجة تطبيقات قيد التطوير أو تعتمد على واجهة برمجة تطبيقات أخرى غير مستقرة.

على الرغم من أنّه يتم عادةً تضمين واجهات برمجة التطبيقات التي تم وضع علامة "تجريبية" أو "غير مستقرة" عليها في المعاينات، إلا أنّ بعض المكتبات تتضمّن واجهات برمجة تطبيقات تم وضع علامة "تجريبية" أو "غير مستقرة" عليها.

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

السلوك الديناميكي

تتصرف بعض المكتبات بشكل مختلف استنادًا إلى عوامل خارجية. على سبيل المثال، تعتمد المكتبة التي تتصل بأحد الخوادم على التغييرات في هذا الخادم.

  • هل يجب أن تتطابق المكتبة مع إصدار معيّن من الخادم؟
  • هل يمكن للمكتبة الاتصال بإصدارات مختلفة من الخادم؟
  • هل هناك عامل خارجي آخر يؤثر في الأداء السليم للمكتبة؟

دمج ملفات البيان

يمكن أن تحتوي المكتبات المنشورة كأرشيفات Android (AAR) على موارد وملفات بيان تم دمجها في تطبيقك. ويمكن أن تضيف هذه المكونات أذونات جديدة ومكونات Android، مثل الأنشطة أو تطبيقات البث التي تعمل بشكل غير مباشر.

التحديثات أثناء التشغيل

تستخدِم بعض المكتبات ميزات يمكن تحديثها خارج نطاق التحكّم في تطبيقك. قد تستخدم المكتبة "خدمات Play" التي يتم ترقيتها بشكل مستقل عن حزمة تطوير البرامج (SDK) لنظام التشغيل Android. يمكن أن ترتبط المكتبات الأخرى بالخدمات في التطبيقات الخارجية التي يتم تحديثها بشكل مستقل (غالبًا باستخدام لغة تعريف واجهة نظام Android ‏(AIDL)).

كم عدد الإصدارات التي تتخطّاها؟

وكلما طال انتظارك لترقية مكتبة، زادت المخاطر المحتملة. إذا لاحظت تغييرًا كبيرًا في إصدار معيّن، مثل 1.2.3 إلى 1.34.5، انتبه إلى هذه المكتبة بشكلٍ خاص.

أدلة نقل البيانات

تحقَّق ممّا إذا كانت المكتبة تتوفّر لديها دليل نقل البيانات. ويمكن أن يؤدي ذلك إلى تقليل تحليل المخاطر والتخطيط للتخفيف من حدتها بشكل كبير.

يُرجى العِلم أنّ توفُّر دليل مماثل هو مؤشر جيد على أنّ المطوِّر قد ركّز على التوافق وأخذ في الاعتبار تخفيف عملية الترقية.

ملاحظات الإصدار

اطّلِع على ملاحظات الإصدار (إذا كانت متوفّرة) لكل مكتبة تم تغييرها. ابحث عن مؤشرات على التغييرات المفاجئة أو المتطلبات الجديدة، مثل الأذونات المُضافة.

ملفات README

تشير بعض ملفات README لمكتبة إلى المخاطر المحتملة، خاصةً إذا لم تقدم المكتبة ملاحظات الإصدار. ابحث عن _المشاكل المعروفة_، خاصةً المشاكل المعروفة المتعلّقة بالأمان.

التحقّق من الثغرات الأمنية المعروفة

تتتبّع أداة Play SDK Index الثغرات الأمنية في العديد من حِزم SDK الشائعة. تُبلِغ أداة Play Console عن ما إذا كنت تستخدم إحدى حِزم SDK المُدرَجة التي تتضمن ثغرات أمنية معروفة. عند تعديل ملفات الإصدارات في "استوديو Android"، يتحقّق بيئة التطوير المتكاملة (IDE) من فهرس حزمة تطوير البرامج (SDK) ويرصد استخدام إصدارات المكتبة المعرَّضة للاختراق.

يدير المعهد الوطني للمعايير والتكنولوجيا (NIST) قاعدة بيانات وطنية كبيرة حول الثغرات الأمنية (NVD). يتحقّق المكوّن الإضافي Dependency Check من Gradle من التبعيات المستخدمة مقارنةً بـ NVD.

لاستخدام أداة Dependency Check، عليك طلب مفتاح واجهة برمجة التطبيقات NVD API وإعداد المكوّن الإضافي Gradle وتشغيل ./gradlew dependencyCheckAnalyze. يُرجى العِلم أنّ تنفيذ هذا الإجراء قد يستغرق وقتًا طويلاً.

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

هل يمكن حل الإصدارات على النحو المتوقّع؟ ابحث عن التعارضات، خاصةً الاختلافات الرئيسية في الإصدارات. راجع حل تبعية Gradle للحصول على تفاصيل حول كيفية البحث عن التعارضات. على وجه الخصوص، ابحث عن -> في تقرير ./gradlew app:dependencies.

عندما يكون ذلك ممكنًا، قم بالعمل مع مؤلفي التبعية لسحق تبعياتهم. إذا كانت شركتك تسمح بذلك، يمكنك المساهمة بالتغييرات في المكتبة (التحميل) للمساعدة في تحسين توافق المكتبة.

التحقّق من التراخيص

ابحث عن التغييرات في التراخيص عند ترقية مكتبة. قد تتغير المكتبة نفسها إلى ترخيص لم يعُد متوافقًا مع تطبيقك أو مكتبتك. يمكن أن تؤدي أيضًا التبعية الجديدة غير المباشرة إلى ظهور تراخيص غير متوافقة. اطّلِع على التحقّق من صحة التراخيص لمعرفة تفاصيل عن التحقّق من المجموعة الحالية من التراخيص في جميع التبعيات.

مخاطر الصيانة و
الجودة

بالنسبة إلى المكتبات التي تتضمّن مستودعات عامة:

  • كم عدد المساهمين الذين يحافظون على هذه المكتبة؟
  • متى كانت آخر ترقية، وكم مرة تتغيّر المكتبة؟
  • ما هو شكل قائمة المشاكل المُرسَلة (إن توفّرت)؟ اطّلِع على هذه التقارير للحصول على فكرة عن المشاكل المحتمَلة والمشاكل الفنية في المكتبة.
  • ما مدى تغطية اختبارات الوحدة للمكتبة؟
  • هل هناك أنماط مضادة معروفة في قاعدة البيانات؟
  • هل المكتبة موثَّقة جيدًا؟
  • هل هناك العديد من تعليقات _fixme_ في قاعدة البيانات؟

البرامج المفتوحة المصدر في مقابل البرامج المغلقة المصدر

إذا كانت المكتبة مفتوحة المصدر، سيكون من الأسهل تصحيح الأخطاء فيها مقارنةً بالمكتبات المغلقة المصدر، سواء كانت المشاكل في الرمز البرمجي الخاص بك أو في رمز المكتبة.

الحدّ من الاعتماد على المصادر المغلقة وإجراء فحص إضافي أثناء تقييمها هل هناك بدائل جيدة تناسب حالة الاستخدام؟ ما هي اتفاقيات مستوى الخدمة المتاحة للمكتبات ذات المصدر المغلق؟ إذا اخترت استخدام تبعية مصدر مغلق، عليك الاستعداد لكتابة حالات اختبار إضافية للمساعدة في الحد من المخاطر.

تشغيل إصدار

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

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

استخدام أداة lint لرصد مشاكل واجهة برمجة التطبيقات

يمكن أن يرصد أداة lint لنظام التشغيل Android العديد من المشاكل في تطبيقك، بما في ذلك بعض المشاكل الناتجة عن تغيير إصدارات التبعيات أو حزمة تطوير البرامج (SDK) لنظام التشغيل Android. على سبيل المثال، إذا كنت تستخدم إصدارًا قديمًا من compileSdk وترقية إلى إصدار جديد منه واستخدام واجهات برمجة التطبيقات الجديدة، سيُبلغك lint بتلك الواجهات غير المتوفّرة في الإصدارات السابقة من حزمة SDK.

تعمل أداة Lint في محرِّر "استوديو Android"، ويتم الإبلاغ عن المشاكل أثناء إجراء التغييرات. لا يتم عادةً تنفيذ هذا الإجراء كجزء من عملية إنشاء المحتوى في "استوديو YouTube" أو عند تنفيذ سطر أوامر، ما لم يتم استخدام الهدفَين build أو lint.

إذا كنت تستخدم ميزة الدمج المستمر (CI)، يمكنك تشغيل gradlew build أو gradlew lint أثناء عمليات إنشاء CI (أو على الأقل أثناء عمليات الإنشاء النهارية ) لرصد هذه الأنواع من الأخطاء.

إذا كنت لا تستخدم عملية دمج الإصدارات، احرص على تنفيذ gradlew lint من حين لآخر على الأقل.

يجب إيلاء اهتمام خاص لأخطاء أداة Lint وتحذيراتها. يتم شحن بعض المكتبات مع عمليات التحقّق من الأخطاء النحوية الخاصة بها، ما يساعد في ضمان الاستخدام الصحيح لواجهة برمجة التطبيقات. تتضمن بعض الإصدارات الجديدة من المكتبة تحذيرات وأخطاء جديدة لأداة Lint، مما يؤدي إلى إنشاء تقارير جديدة عند الإنشاء.

الحدّ من المخاطر

بعد تحديد مخاطر الترقية، حدِّد الطريقة التي تريد التخفيف منها:

  • قبول بعض المخاطر على وضعها الحالي: تكون بعض المخاطر منخفضة بما يكفي لتكون مقبولة، خاصةً عندما يكون وقت الترقية والموارد محدودة.
  • رفض بعض المخاطر بشكل قاطع قد تبدو بعض الترقيات محفوفة بالمخاطر، خاصةً إذا كان لديك وقت أو موارد محدودة للحدّ من هذه المخاطر في الوقت الحالي. إذا كنت بحاجة إلى تحديد الأولويات، ركِّز على الترقيات اللازمة للمشاكل التي واجهتها أو الميزات الجديدة التي تحتاج إليها.
  • الحد من المخاطر المتبقية
    • ننصحك بتجميع الترقيات في مجموعات أصغر حجمًا ومستقلّة من التغييرات. ويؤدي ذلك إلى الحد من المخاطر العامة والسماح بإلغاء التغييرات جزئيًا.
    • التحقيق في التغييرات بالتفصيل
    • اختبِر تطبيقك للتحقق من التغييرات غير المتوقعة. أضِف اختبارات جديدة عند الحاجة لتعزيز الثقة في عملية الترقية.
    • راجِع المصدر (إن توفّر) عند العثور على محتوى مريب.
    • أدخِل التغييرات المطلوبة في المصدر أو الإصدار.

توثيق قراراتك إذا أصبحت مخاطر الترقية مشاكل عند تشغيل تطبيقك، يمكن أن تقلل مستندات تحليل المخاطر من الحاجة إلى تحليل الأخطاء.

التحقّق من التراخيص

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

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

إذا كان الترخيص غير متوافق (أو تغيّر ليصبح غير متوافق)، لا يمكنك استخدام هذا الإصدار من المكتبة. يمكنك:

  • تواصل مع مالك المكتبة واطلب استمرار الترخيص الحالي أو الترخيص المزدوج لمواصلة السماح بالترخيص القديم.
  • يمكنك العمل مع فريقك القانوني لتحديد ما إذا كان بإمكانك تغيير ترخيصك ليصبح متوافقًا.
  • ابحث عن مكتبة أخرى تتضمّن ترخيصًا متوافقًا وعدِّل تطبيقك كما هو مطلوب.
  • يمكنك إنشاء نسخة من آخر إصدار متوافق من المكتبة (إذا كان هذا الترخيص يسمح بإنشاء مشتقات والتغييرات ليست بأثر رجعي) وإجراء التغييرات التي تريدها.