نسخه های وابستگی را ارتقا دهید، نسخه های وابستگی را ارتقا دهید

ارتقاء وابستگی‌ها به شما امکان می‌دهد به آخرین ویژگی‌ها، رفع اشکال‌ها و بهبودها دسترسی داشته باشید. برای ارتقاء وابستگی‌های خود، باید بدانید که Gradle چگونه نسخه‌های درخواستی شما را حل می‌کند ، خطرات مربوط به آن و اقداماتی که می‌توانید برای کاهش آن خطرات انجام دهید.

توجه: تست‌های خوب برنامه برای اطمینان از اینکه ارتقاء ساخت یا برنامه شما را به روش‌های غیرمنتظره‌ای خراب نمی‌کند، کلیدی است.

استراتژی ارتقا خود را در نظر بگیرید

مهمترین مرحله برای هر ارتقا، تجزیه و تحلیل ریسک است. تعیین کنید که با هر وابستگی که ارتقا می دهید چقدر راحت هستید. هنگام تعریف استراتژی ارتقا، ملاحظات زیادی وجود دارد، از جمله:

یک کتابخانه بسازید	آیا برنامه ای می سازید که کاربران آن را دانلود و بر روی دستگاه اجرا کنند؟ یا در حال ساختن یک کتابخانه برای کمک به توسعه دهندگان دیگر در ساخت برنامه های خود هستید؟ اگر در حال ساختن یک برنامه هستید، تمرکز شما باید به روز و پایدار نگه داشتن برنامه باشد. اگر در حال ساخت یک کتابخانه هستید، تمرکز شما باید روی برنامه های دیگر توسعه دهندگان باشد. ارتقاهای شما بر مصرف کنندگان شما تأثیر می گذارد. اگر یکی از وابستگی‌های خود را ارتقا دهید، آن نسخه کاندیدای رزولوشن وابستگی Gradle می‌شود و احتمالاً استفاده برنامه از آن وابستگی را قطع می‌کند. اول - تا حد امکان وابستگی های کتابخانه خود را به حداقل برسانید. هرچه وابستگی های کمتری داشته باشید، تأثیر کمتری بر روی وضوح وابستگی مصرف کننده شما خواهد داشت. حتماً از نسخه‌سازی معنایی پیروی کنید تا به انواع تغییراتی که ایجاد می‌کنید کمک کند. برای مثال، AndroidX از نسخه‌سازی معنایی پیروی می‌کند و یک طرح نسخه‌سازی پیش از انتشار را اضافه می‌کند. سعی کنید از ارتقاء نسخه major خودداری کنید تا از شکستن مشتریان خود جلوگیری کنید. ایجاد یک نامزد انتشار (RC) از کتابخانه خود را برای آزمایش زودهنگام کاربران در نظر بگیرید. برای جزئیات بیشتر در مورد سازگار نگه داشتن رابط باینری برنامه (ABI) کتابخانه خود ، به دستورالعمل های سازگاری با عقب برای نویسندگان کتابخانه مراجعه کنید. از تست‌های یکپارچه‌سازی و ابزارهایی مانند اعتبارسنجی سازگاری باینری استفاده کنید تا مطمئن شوید تغییرات ABI شما با تغییر نسخه مورد نظر شما مطابقت دارد. اگر برای نسخه‌های پایین‌تر کتابخانه خود، اصلاحاتی را در یک patch منتشر کنید، مصرف‌کنندگان شما نیازی ندارند کتابخانه شما را به نسخه major یا minor بعدی ارتقا دهند، مگر اینکه ویژگی‌های جدیدی بخواهند. از ارتقاء وابستگی های گذرا در این ارتقاها اجتناب کنید. اگر ارتقاء کتابخانه شما نیاز به تغییراتی دارد که ممکن است برای مصرف کنندگان شما دردناک باشد، انتشار آنها را به عنوان یک مصنوع جدید در نظر بگیرید تا نسخه های قدیمی و جدید بتوانند در کنار هم قرار بگیرند و امکان عرضه تدریجی تری را فراهم کنند. توجه : اگر ارتقاء به یکی از وابستگی‌های شما حاوی یک تغییر عمده API باشد، احتمالاً می‌خواهید آن را در نسخه major یا minor ارتقا دهید و تغییرات لازم را اعمال کنید. اگر این کار را نکنید، کاربران کتابخانه شما ممکن است این کار را انجام دهند و باعث ایجاد ناسازگاری بین کتابخانه شما و آن وابستگی شود. این ممکن است اعمال شود حتی اگر تغییری در کتابخانه شما ایجاد نشود. شما می توانید نسخه جدیدی را فقط برای ارتقاء آن وابستگی منتشر کنید.
چرخه انتشار	هر چند وقت یکبار برنامه یا کتابخانه خود را منتشر می کنید؟ چرخه های توسعه و انتشار کوتاه تر زمان کمتری برای ارتقا وجود دارد. شما می توانید به سرعت پشت سر بگذارید. ارتقاهای کوچک مکرر می تواند حجم کار را کاهش دهد. اگر ارتقای کتابخانه مشکل ساز شد، می توانید سریعتر آن ارتقا را به عقب برگردانید. ابزارهایی مانند Dependabot و Renovate حجم کار را کاهش می دهند، اما مطمئن شوید که نتایج را تجزیه و تحلیل کنید تا خطرات را بررسی کنید. چرخه های توسعه و انتشار طولانی تر زمان بیشتری برای ایجاد و آزمایش ارتقاها وجود دارد. نسخه های جدیدتر وابستگی ها به احتمال زیاد در طول چرخه شما منتشر می شوند. بازگرداندن به‌روزرسانی‌ها و انتشار برنامه یا کتابخانه شما بیشتر طول می‌کشد.
با آخرین ویژگی ها همراه باشید	آیا ترجیح می‌دهید از جدیدترین ویژگی‌ها و APIهای موجود استفاده کنید یا فقط زمانی که به یک ویژگی یا رفع اشکال نیاز دارید ارتقا دهید؟ معاوضه های ارتقاء مکرر را در نظر بگیرید. به روز رسانی های آینده آسان تر هستند (تغییرات کمتری برای یکپارچه سازی)، اما شما بیشتر در معرض خطرات ارتقا هستید. آزمایش ارتقاء به نسخه های پیش از انتشار (آلفا، بتا، کاندید انتشار) کتابخانه ها می تواند به آمادگی زمانی که نسخه های پایدار در دسترس هستند کمک کند.
وابستگی جدید	اگر یک وابستگی جدید اضافه می‌کنید، یک فرآیند بازبینی قوی را در نظر بگیرید که آن کتابخانه را برای همه معیارهای خطر بررسی می‌کند تا اطمینان حاصل شود که آنها به درستی ارزیابی شده‌اند. اجازه ندهید وابستگی های جدید بدون بررسی اضافه شوند.
تیم اختصاصی	آیا تیم ساخت اختصاصی دارید؟ آیا مهندسان نرم افزار شما ساخت را حفظ می کنند؟ یک تیم اختصاصی اغلب می تواند زمان بیشتری را صرف تجزیه و تحلیل خطرات ارتقاء و آزمایش نسخه های جدید کند تا مطمئن شود که سازه به درستی کار می کند قبل از اینکه مهندسان از نسخه های جدید استفاده کنند.
نوع ارتقا	برخی از ارتقاءها مهمتر از سایرین هستند. به این فکر کنید که کدام یک برای شما مهم است. ارتقاء ابزار بیلد، مانند پلاگین های Gradle و Gradle، معمولاً تأثیر کمتری بر کاربران شما دارد و بسیاری از خطرات داخلی ساخت شما است. خود بیلد به اعتبارسنجی این تغییرات کمک می کند. اعتبار سنجی ارتقاء کتابخانه و SDK دشوارتر است و خطر بیشتری برای کاربران شما ایجاد می کند. پلاگین Android Gradle (AGP) – ابزاری که برای ساخت اپلیکیشن یا کتابخانه اندروید شما استفاده می شود. این مهم‌ترین ارتقایی است که می‌توانید انجام دهید، زیرا اغلب شامل بهبود عملکرد، رفع اشکالات، قوانین جدید پرز و پشتیبانی از نسخه‌های جدید پلتفرم اندروید می‌شود یا آن را فعال می‌کند. Gradle – هنگام ارتقاء AGP یا پلاگین Gradle دیگر، اغلب باید Gradle را ارتقا دهید. سایر پلاگین های Gradle - گاهی اوقات API پلاگین Gradle تغییر می کند. هنگامی که Gradle را ارتقا می دهید، ارتقاء افزونه هایی را که استفاده می کنید بررسی کنید. Kotlin و Java – برخی از کتابخانه‌ها و افزونه‌ها به حداقل نسخه‌های Kotlin یا Java نیاز دارند، یا می‌خواهید از ویژگی‌های زبان جدید، APIها یا بهبود عملکرد استفاده کنید. پلتفرم Android - فروشگاه Play به ارتقاء منظم Android SDK نیاز دارد. باید در اسرع وقت نسخه های جدید Android SDK را آزمایش کنید. برخی از ارتقاهای SDK به تغییراتی در برنامه شما نیاز دارند، مانند مجوزهای جدید یا استفاده از APIهای جدید. کتابخانه ها - آیا می خواهید کتابخانه ها را بر اساس نزدیکی آنها به معماری کلی خود اولویت بندی کنید؟ کتابخانه‌های مرتبط با پلتفرم و معماری، مانند AndroidX، اغلب برای استفاده از ویژگی‌های جدید یا کمک به تغییرات انتزاعی در پلتفرم تغییر می‌کنند. حداقل هر زمان که پلتفرم اندروید یا سایر کتابخانه های مرتبط با معماری را ارتقا می دهید، این کتابخانه ها را ارتقا دهید. سایر ارتقاء کتابخانه را می توان گسترش داد یا به تأخیر انداخت مگر اینکه به یک ویژگی جدید یا رفع اشکال خاص نیاز داشته باشید. Android Studio — به روز نگه داشتن Android Studio به شما امکان می دهد به جدیدترین ویژگی ها و رفع اشکال در پلتفرم و ابزارهای زیربنایی IntelliJ IDEA دسترسی داشته باشید تا با جدیدترین SDK های Android کار کنید.
ابزار موجود	ابزارها و پلاگین های زیادی برای کمک به ارتقاء شما وجود دارد. ابزارهایی مانند Dependabot و Renovate به طور خودکار نسخه های کتابخانه را در ساخت شما ارتقا می دهند، اما مطمئن شوید که نتایج را برای بررسی خطرات آنالیز کنید.

استراتژی برای انواع خاصی از ارتقاء

ارتقاء برخی از انواع وابستگی ها ممکن است یک اثر آبشاری داشته باشد و نیاز به ارتقاء انواع دیگر وابستگی ها داشته باشد. ما در مورد روابط بین عناصر ساخت در وابستگی های متقابل ابزار و کتابخانه بحث می کنیم.

شکل 1. ایجاد روابط.

هنگام ارتقاء هر نوع کامپوننت، نحوه تأثیر ارتقاء بر سایر اجزای ساخت را در نظر بگیرید.

پلاگین Android Gradle (AGP)	Android Studio دارای یک دستیار ارتقاء AGP است که می تواند در انجام این کارها کمک کند. اگر از دستیار استفاده می کنید یا ارتقا را به صورت دستی انجام می دهید، موارد زیر را در نظر بگیرید: به یادداشت های انتشار AGP نگاه کنید. Gradle را حداقل به نسخه ذکر شده ارتقا دهید . Android Studio را به نسخه ای ارتقا دهید که از نسخه انتخابی AGP پشتیبانی می کند. از نسخه‌های Android Studio و AGP استفاده کنید که از Android SDK مورد نظر شما پشتیبانی می‌کنند . سازگاری با SDK Build Tools، NDK و JDK را بررسی کنید. اگر یک پلاگین Gradle (برای استفاده داخلی یا عمومی) ایجاد می کنید که داده های AGP را گسترش می دهد یا از آن استفاده می کند، بررسی کنید که آیا نیاز به ارتقاء افزونه خود دارید یا خیر. گاهی اوقات AGP API ها را منسوخ می کند و بعداً حذف می کند و باعث ناسازگاری با افزونه های قبلی می شود.
کامپایلر Kotlin، زبان و زمان اجرا	یادداشت های انتشار Kotlin را برای مشکلات و ناسازگاری های شناخته شده بررسی کنید. اگر از Jetpack Compose استفاده می کنید: اگر نسخه جدید Kotlin کمتر از 2.0.0 است: افزونه کامپایلر Compose سازگار را پیدا کنید. kotlinCompilerExtensionVersion در build.gradle.kts هر ماژول که در آن ظاهر می شود ارتقا دهید. اگر نسخه جدید Kotin 2.0.0 یا بالاتر است: پلاگین Compose Compiler Gradle را با همان نسخه کامپایلر Kotlin تنظیم کنید. اگر از پردازش نمادهای Kotlin (KSP) استفاده می‌کنید، برای راه‌اندازی به KSP Quick Start و برای نسخه‌های موجود به نسخه‌های KSP مراجعه کنید. توجه داشته باشید که باید از نسخه ای از KSP استفاده کنید که با نسخه Kotlin مطابقت داشته باشد. برای مثال، اگر از Kotlin 2.0.21 استفاده می کنید، می توانید از هر نسخه ای از پلاگین KSP که با 2.0.21 شروع می شود، مانند 2.0.21-1.0.25 استفاده کنید. شما معمولاً نیازی به ارتقاء پردازنده‌های KSP ندارید (مانند کامپایلر Room ، که به عنوان یک وابستگی ksp در فایل‌های ساخت شما ظاهر می‌شود). پلاگین KSP بیشتر API کامپایلر را خلاصه می کند و KSP API مورد استفاده پردازنده ها پایدار است. سایر پلاگین های کامپایلر Kotlin را که استفاده می کنید ارتقا دهید. Kotlin Compiler Plugin API اغلب بین نسخه ها تغییر می کند و افزونه ها باید از یک API سازگار استفاده کنند. اگر افزونه در افزونه های کامپایلر فهرست شده است، باید از همان نسخه کامپایلر Kotlin استفاده کنید. برای هر افزونه کامپایل دیگری، مستندات آنها را برای نقشه برداری مناسب بررسی کنید. توجه داشته باشید که پلاگین های کامپایلری که در کنار خود کامپایلر Kotlin نگهداری نمی شوند، اغلب با تأخیر انتشار مواجه می شوند زیرا منتظر می مانند تا API افزونه کامپایلر تثبیت شود. قبل از ارتقای Kotlin، بررسی کنید که همه افزونه‌های کامپایلری که استفاده می‌کنید دارای ارتقاء منطبق باشند. در نهایت، در برخی موارد، زبان Kotlin تغییر می کند و شما را ملزم به به روز رسانی کد خود می کند. این اغلب زمانی اتفاق می‌افتد که ویژگی‌های آزمایشی را امتحان کنید. اگر کد شما پس از ارتقاء کامپایلر Kotlin به درستی ساخته نشد، تغییرات زبان یا شکستگی کتابخانه زمان اجرا را در یادداشت‌های انتشار Kotlin بررسی کنید.
پلاگین های کامپایلر Kotlin	اگر نیاز به ارتقاء یک افزونه کامپایلر Kotlin دارید، به نسخه مشابه Kotlin که در حال استفاده است ارتقا دهید. اکثر افزونه های کامپایلر Kotlin یا از همان نسخه کامپایلر Kotlin استفاده می کنند یا با نسخه مورد نیاز کامپایلر Kotlin شروع می شوند. به عنوان مثال، اگر نسخه افزونه 2.0.21-1.0.25 است، باید از نسخه 2.0.21 کامپایلر Kotlin استفاده کنید. تغییر نسخه کامپایلر Kotlin گاهی به تغییرات دیگری نیاز دارد.
کتابخانه ها	کتابخانه ها رایج ترین وابستگی ارتقا یافته در ساخت شما هستند. ارتقاهای موجود را در ویرایشگر Android Studio یا اگر از برخی ابزارها و افزونه‌های وابستگی استفاده می‌کنید، مشاهده خواهید کرد. برخی از کتابخانه ها حداقل compileSdk یا minSdk مورد نیاز برای استفاده از کتابخانه را مشخص می کنند. اگر حداقل از compileSdk مشخص شده استفاده نکنید، بیلدهای شما با شکست مواجه می شوند. با این حال، minSdk برنامه شما به طور خودکار روی حداکثر تمام مقادیر minSdk تعیین شده در وابستگی های کتابخانه و فایل های ساخت شما تنظیم می شود. برخی از کتابخانه ها نیز حداقل نسخه Kotlin را برای استفاده مشخص می کنند. نسخه Kotlin را در فایل های ساخت خود به روز کنید تا حداقل نسخه مشخص شده باشد.
گریدل	گاهی اوقات نسخه‌های جدید Gradle APIهای موجود را منسوخ می‌کنند و در نسخه‌های بعدی آن APIها را حذف می‌کنند. اگر پلاگین Gradle را توسعه می دهید، در اسرع وقت افزونه خود را ارتقا دهید، به خصوص اگر آن افزونه عمومی است. برخی از ارتقاء Gradle نیازمند مکان یابی نسخه های جدید افزونه هایی است که استفاده می کنید. توجه داشته باشید که این پلاگین‌ها می‌توانند در توسعه خود تاخیر داشته باشند زیرا افزونه‌ها را برای مطابقت با آخرین APIهای پلاگین Gradle ارتقا می‌دهند. برای ارتقا Gradle: یادداشت های انتشار را برای نسخه ای که می خواهید استفاده کنید بخوانید. نسخه Gradle را در gradle/wrapper/gradle-wrapper.properties ارتقا دهید. با اجرای ./gradlew wrapper --gradle-version latest jar و اسکریپت های Gradle را ارتقا دهید. پلاگین های Gradle خود را ارتقا دهید. JDK مورد استفاده برای اجرای Gradle را ارتقا دهید.
پلاگین های Gradle	پلاگین های Gradle ارتقا یافته گاهی اوقات از API های Gradle جدید یا تغییر یافته استفاده می کنند که به نوبه خود نیاز به ارتقاء Gradle یا احتمالاً تغییر در پیکربندی آنها در فایل های ساخت شما دارند. در هر صورت، هشدارهای ساخت یا خطاهایی را برای نشان دادن ناسازگاری مشاهده خواهید کرد. هر زمان که پلاگین ها را ارتقا می دهید، Gradle را ارتقا دهید.
Android SDK	Android Studio شامل یک دستیار ارتقا SDK Android است که می تواند در انجام این کارها کمک کند. اگر از دستیار استفاده می کنید یا ارتقا را به صورت دستی انجام می دهید، موارد زیر را در نظر بگیرید: هر نسخه از Android SDK حاوی ویژگی‌ها و APIهای جدید، رفع اشکال‌ها و تغییرات رفتاری است. فروشگاه Play نیاز به به‌روزرسانی targetSdk شما دارد ، اما به‌روزرسانی targetSdk را زودتر از موعد مقرر در نظر بگیرید تا زمان بیشتری برای ایجاد تغییرات لازم در نظر بگیرید. قبل از ارتقا SDK Android، یادداشت‌های انتشار را با دقت بخوانید. به بخش تغییرات رفتاری که شامل: مجوزهای جدیدی که باید در زمان نصب یا اجرا درخواست کنید. API های منسوخ و جایگزین های آنها. شکستن تغییرات در APIها یا رفتار. API های جدید Kotlin یا Java، که ممکن است روی کد شما تأثیر بگذارد. بخش تغییرات رفتار می تواند بسیار طولانی باشد، اما به دقت توجه کنید زیرا اغلب شامل تغییرات مهمی است که باید در برنامه خود ایجاد کنید. شما باید targetSdk ارتقا دهید تا نیازهای فروشگاه Play را برآورده کنید. ارتقاء compileSdk اختیاری است و به شما امکان دسترسی به API های جدید را می دهد. توجه داشته باشید که برخی از کتابخانه ها، مانند AndroidX، دارای حداقل نیاز compileSdk هستند. برای استفاده از ویژگی‌های جدید SDK در حین توسعه و اطمینان از سازگاری در طول ساخت، افزونه Android Gradle (AGP) و Android Studio را ارتقا دهید. اینها شامل ابزارهای جدید و بهبودیافته برای SDKهای جدید است. حداقل نسخه ابزارها برای سطح API Android را ببینید. هنگام ارتقای Android SDK، کتابخانه‌های AndroidX را که استفاده می‌کنید ارتقا دهید. AndroidX اغلب از API های جدید و به روز شده برای سازگاری و عملکرد بهتر در نسخه های Android SDK استفاده می کند.
اندروید استودیو	به طور کلی می توانید اندروید استودیو را در هر زمانی ارتقا دهید. ممکن است پیام هایی را مشاهده کنید که از شما می خواهند AGP را ارتقا دهید یا Android SDK را ارتقا دهید . این ارتقاها به شدت توصیه می شوند اما لازم نیستند. اگر بعداً می‌خواهید از Android Studio برای ارتقا AGP یا Android SDK استفاده کنید، می‌توانید این گزینه‌ها را در منوی Tools پیدا کنید: دستیار ارتقاء AGP… دستیار ارتقا SDK Android…
جاوا	اگر کد منبع جاوا را در برنامه اندروید خود دارید، ممکن است بخواهید از API های جاوا جدیدتر استفاده کنید. هر نسخه Android SDK از زیر مجموعه ای از API های جاوا و ویژگی های زبان پشتیبانی می کند. AGP با استفاده از فرآیندی به نام desgaring سازگاری را برای نسخه‌های پایین‌تر SDK Android فراهم می‌کند. یادداشت‌های انتشار Android SDK مشخص می‌کنند که کدام سطح جاوا پشتیبانی می‌شود و مشکلات احتمالی وجود دارد. برخی از این مسائل ممکن است بر کد منبع Kotlin نیز تأثیر بگذارد، زیرا Kotlin به همان APIهای جاوا دسترسی دارد. حتماً به بخش‌های JDK API که در بخش تغییرات رفتاری یادداشت‌های انتشار ظاهر می‌شوند، دقت کنید، حتی اگر کد منبع جاوا ندارید. استفاده از JDK در چندین مکان در اسکریپت های ساخت شما مشخص شده است. برای اطلاعات بیشتر به نسخه های جاوا در بیلد اندروید مراجعه کنید.

تجزیه و تحلیل ارتقا

ارتقاء یک وابستگی می تواند خطراتی را در قالب تغییرات API و رفتار، الزامات جدید برای استفاده، مسائل امنیتی جدید یا حتی تغییرات مجوز ایجاد کند. به عنوان مثال، آیا شما نیاز دارید:

• کد تغییرات API را تغییر دهید؟
• بررسی‌های مجوز جدید اضافه شود؟
• آزمایش‌های اضافی ایجاد کنید یا آزمایش‌های موجود را برای تغییرات رفتار اصلاح کنید؟

در نظر بگیرید که وابستگی که ارتقا داده اید، نسخه های وابستگی های خود را ارتقا داده است. این می تواند به سرعت به مجموعه ای عظیم از تغییرات تبدیل شود.

اگر از ابزاری مانند Renovate یا Dependabot برای خودکارسازی ارتقاهای خود استفاده می کنید، توجه داشته باشید که آنها هیچ تحلیلی برای شما انجام نمی دهند. آنها به آخرین نسخه های کتابخانه ارتقا می یابند. تصور نکنید که همه چیز پس از این نوع ارتقاء خودکار به درستی کار خواهد کرد .

کلید ارتقاء موفقیت آمیز تجزیه و تحلیل ارتقاء است:

1. تفاوت های وابستگی را از قبل و بعد از ارتقاء خود تعیین کنید.
2. هر تغییر را بررسی کنید و خطرات مربوطه را تعیین کنید.
3. خطرات را کاهش دهید یا تغییرات را بپذیرید یا رد کنید.

تفاوت های وابستگی را تعیین کنید

اولین قدم در تجزیه و تحلیل ارتقاء شما این است که تعیین کنید وابستگی های شما چگونه تغییر می کند. از کنترل نسخه (VCS، مانند Git) و افزونه Dependency Guard برای مشاهده سریع تغییرات استفاده کنید. هدف شما ایجاد یک عکس فوری قبل و بعد و مقایسه آنهاست.

اولین خط پایه خود را تنظیم و ایجاد کنید

قبل از شروع ارتقا، مطمئن شوید که پروژه شما با موفقیت ساخته شده است.

در حالت ایده‌آل، تا حد امکان اخطارها را حل کنید، یا خطوط پایه ایجاد کنید تا اخطارهایی را که قبلاً دیده‌اید، ردیابی کنید.

• پرز: اخطارهای پرز موجود خود را بررسی کنید و یک خط پایه لینت اندروید ایجاد کنید.
• کامپایلر Kotlin:
  • برای تلقی همه هشدارها به عنوان خطا -Werror فعال کنید. نحوه تعریف گزینه ها را ببینید.
  • استفاده از افزونه‌هایی مانند خط پایه هشدار Kotlin یا Generator پایه هشدارهای Kotlin را در نظر بگیرید.
• سایر ابزارها: اگر از سایر ابزارهای تجزیه و تحلیل استاتیک (مانند Detekt ) استفاده می کنید که از ردیابی خط پایه پشتیبانی می کنند، خطوط پایه آنها را تنظیم کنید.

این خطوط پایه هشدار، دیدن هشدارهای جدید معرفی شده در حین ارتقاء وابستگی های خود را آسان تر می کند.

با راه اندازی و اجرای Dependency Guard یک خط پایه وابستگی ایجاد کنید. در کاتالوگ نسخه gradle/libs.versions.toml خود، اضافه کنید:

[versions]
dependencyGuard = "0.5.0"

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

و موارد زیر را به فایل ساخت اپلیکیشن خود اضافه کنید:

کاتلین

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 یا Kotlin Warnings Baseline Generator ، به هشدارهای جدید رسیدگی کنید و خطوط پایه آنها را نیز به روز کنید.

برای به روز رسانی گزارش پایه خود ./gradlew dependencyGuard اجرا کنید. سپس VCS diff خود را اجرا کنید تا تغییرات غیرکتابخانه ای را ببینید. به احتمال زیاد شامل ارتقاهای کتابخانه بسیار بیشتری از آنچه فکر می کردید خواهد بود.

ریسک ها را تحلیل کنید

هنگامی که متوجه شدید چه چیزی تغییر کرده است، خطرات احتمالی هر کتابخانه ارتقا یافته را در نظر بگیرید. این به تمرکز روی آزمایش یا بررسی عمیق تر تغییرات شما کمک می کند. مجموعه ای از ریسک ها را برای تجزیه و تحلیل پروژه خود تعریف کنید تا از تجزیه و تحلیل منسجم اطمینان حاصل کنید.

برخی ملاحظات:

برآمدگی های اصلی نسخه	آیا شماره نسخه اصلی تغییر کرده است؟ در نسخه‌سازی معنایی ، عدد اول به عنوان نسخه اصلی شناخته می‌شود. به عنوان مثال، اگر نسخه یک کتابخانه از 1.2.3 به 2.0.1 ارتقا یابد، نسخه اصلی تغییر کرده است. این معمولاً نشان‌دهنده این است که توسعه‌دهنده کتابخانه تغییرات ناسازگاری را بین نسخه‌ها ایجاد کرده است، مانند حذف یا تغییر بخش‌هایی از API. وقتی این را می بینید، هنگام مشاهده هر یک از ملاحظات زیر به کتابخانه های آسیب دیده توجه بیشتری کنید. اگر کد شما از هر API آزمایشی استفاده می کند (که اغلب شما را ملزم می کند با استفاده از حاشیه نویسی یا مشخصات فایل ساخت، شرکت کنید)، حتی تغییرات جزئی یا وصله نسخه، مانند ارتقاء از 1.2.3 به 1.3.1 یا 1.2.3 به 1.2. 5، ممکن است خطرات اضافی ایجاد کند.
Nonstable API	برخی از نسخه های کتابخانه ممکن است شامل API های ناپایدار باشند. اینها معمولاً APIهایی هستند که در حال انجام هستند یا به API ناپایدار دیگری وابسته هستند. در حالی که معمولاً محدود به پیش‌نمایش‌ها، مانند نسخه‌های آلفا، توسعه‌دهنده یا آزمایشی است، برخی از کتابخانه‌ها شامل APIهایی هستند که به صورت آزمایشی یا ناپایدار علامت‌گذاری شده‌اند. در صورت امکان، از چنین APIهایی اجتناب کنید. اگر نیاز به استفاده از آنها دارید، حتماً میزان استفاده خود را ثبت کنید و مراقب تغییرات یا حذف‌ها در نسخه‌های بعدی باشید.
رفتار پویا	برخی از کتابخانه ها بر اساس عوامل خارجی متفاوت رفتار می کنند. به عنوان مثال، کتابخانه ای که با یک سرور ارتباط برقرار می کند به تغییرات آن سرور بستگی دارد. آیا کتابخانه باید با نسخه سرور خاصی مطابقت داشته باشد؟ آیا کتابخانه می تواند به نسخه های مختلف یک سرور متصل شود؟ آیا عامل خارجی دیگری بر رفتار صحیح کتابخانه تأثیر می گذارد؟
ادغام آشکار	کتابخانه‌هایی که به‌عنوان بایگانی Android (AAR) منتشر می‌شوند می‌توانند حاوی منابع و مانیفست‌هایی باشند که در برنامه شما ادغام شده‌اند. اینها می‌توانند مجوزها و مؤلفه‌های Android، مانند فعالیت‌ها یا گیرنده‌های پخش را که به طور غیرمستقیم اجرا می‌شوند، اضافه کنند.
به روز رسانی زمان اجرا	برخی از کتابخانه ها از ویژگی هایی استفاده می کنند که می توانند خارج از کنترل برنامه شما به روز شوند. ممکن است یک کتابخانه از Play Services استفاده کند که مستقل از Android SDK ارتقا یافته است. کتابخانه‌های دیگر ممکن است به سرویس‌های برنامه‌های خارجی به‌روزشده مستقل (اغلب از AIDL) متصل شوند.
چند نسخه را رد می کنید؟	هر چه مدت بیشتری برای ارتقاء کتابخانه صبر کنید، خطرات احتمالی بیشتری خواهید داشت. اگر نسخه ای مانند 1.2.3 تا 1.34.5 به طور قابل توجهی تغییر می کند، توجه بیشتری به این کتابخانه داشته باشید.
راهنمای مهاجرت	بررسی کنید که آیا کتابخانه راهنمای مهاجرت دارد یا خیر. این می تواند به طور قابل توجهی تجزیه و تحلیل ریسک و برنامه ریزی کاهش را کاهش دهد. توجه داشته باشید که وجود چنین راهنما نشان دهنده خوبی است که توسعه دهنده روی سازگاری تمرکز کرده و کاهش ارتقای شما را در نظر گرفته است.
یادداشت های انتشار	به یادداشت‌های انتشار (در صورت ارائه) برای هر کتابخانه تغییر یافته مراجعه کنید. به دنبال نشانه هایی مبنی بر شکستن تغییرات یا الزامات جدید، مانند مجوزهای اضافه شده باشید.
READMEs	برخی از فایل های README برای یک یادداشت کتابخانه خطرات احتمالی را ذکر می کنند، به خصوص اگر کتابخانه یادداشت های انتشار را ارائه ندهد. به دنبال _مشکلات شناخته شده_، به ویژه نگرانی های امنیتی شناخته شده باشید.
آسیب پذیری های شناخته شده را بررسی کنید	Play SDK Index آسیب‌پذیری‌های بسیاری از SDK‌های محبوب را ردیابی می‌کند. کنسول Play گزارش می دهد که آیا از یکی از SDK های فهرست شده با آسیب پذیری های شناخته شده استفاده می کنید یا خیر. هنگام ویرایش فایل‌های ساخت در Android Studio، IDE فهرست SDK را بررسی می‌کند و استفاده از نسخه‌های آسیب‌پذیر کتابخانه را علامت‌گذاری می‌کند. مؤسسه ملی استانداردها و فناوری (NIST) یک پایگاه داده ملی آسیب پذیری (NVD) بزرگ دارد. افزونه Dependency Check Gradle وابستگی های استفاده شده شما را در برابر NVD بررسی می کند. برای استفاده از بررسی وابستگی، یک کلید NVD API درخواست کنید ، افزونه Gradle را راه‌اندازی کنید و ./gradlew dependencyCheckAnalyze اجرا کنید. توجه داشته باشید که اجرای آن ممکن است زمان زیادی طول بکشد.
تضاد نسخه	آیا نسخه ها همانطور که انتظار می رود حل می شوند؟ به دنبال تضادها، به خصوص تفاوت های اصلی نسخه باشید. برای جزئیات بیشتر در مورد اینکه چگونه می توانید به دنبال تضاد بگردید ، به حل وابستگی Gradle مراجعه کنید. به ویژه، -> را در گزارش ./gradlew app:dependencies جستجو کنید. در صورت امکان، با نویسندگان یک وابستگی کار کنید تا وابستگی آنها را از بین ببرید. اگر شرکت شما اجازه می دهد، تغییراتی را در کتابخانه (بالا جریان) انجام دهید تا به بهبود سازگاری کتابخانه کمک کند.
مجوزها را بررسی کنید	هنگام ارتقاء کتابخانه به دنبال تغییرات در مجوزها باشید. خود کتابخانه می تواند به مجوزی تغییر کند که دیگر با برنامه یا کتابخانه شما سازگار نیست. وابستگی های انتقالی جدید همچنین می توانند مجوزهای ناسازگاری را معرفی کنند. برای جزئیات بررسی مجموعه فعلی مجوزها در وابستگی‌هایتان، به تأیید مجوزها مراجعه کنید.
نگهداری و ریسک های کیفیت	برای کتابخانه های دارای مخازن عمومی: چه تعداد مشارکت کننده در حال نگهداری از کتابخانه هستند؟ آخرین به روز رسانی چه زمانی بود و هر چند وقت یکبار کتابخانه تغییر می کند؟ مشکل عقب مانده (در صورت وجود) چگونه است؟ برای دریافت احساس مشکلات احتمالی و بدهی فنی کتابخانه، آن را کم کنید. آزمون های واحد چقدر کتابخانه را پوشش می دهند؟ آیا ضد الگوهای شناخته شده ای در پایگاه کد وجود دارد؟ آیا کتابخانه به خوبی مستند شده است؟ آیا نظرات _fixme_ زیادی در پایگاه کد وجود دارد؟
منبع باز در مقابل منبع بسته	اگر کتابخانه ای متن باز باشد، اشکال زدایی مشکلات آسان تر از منبع بسته است، چه مشکلات در کد شما باشد و چه در کد کتابخانه. وابستگی های منبع بسته را به حداقل برسانید و در طول ارزیابی آنها، بررسی دقیق بیشتری را اعمال کنید. آیا جایگزین های خوبی وجود دارد که مناسب مورد استفاده شما باشد؟ چه توافق نامه هایی در سطح خدمات برای کتابخانه های منبع بسته موجود است؟ اگر تصمیم به استفاده از وابستگی منبع بسته دارید، برای کمک به محدود کردن خطرات، آماده نوشتن موارد آزمایشی اضافی باشید.

یک بیلد را اجرا کنید

پروژه خود را بسازید به دنبال خطاها یا هشدارهای جدید باشید. اگر می توانید تشخیص دهید که کدام کتابخانه باعث ایجاد آنها شده است، به عنوان خطری برای ارتقای آن کتابخانه توجه داشته باشید.

اگر هشدارهای استهلاک جدیدی مشاهده کردید، آن‌ها را به عنوان خطرات خاص برای کتابخانه تولیدکننده آن اضافه کنید. این موارد را می توان در نسخه های بعدی حذف کرد. اگر می‌خواهید به استفاده از آن کتابخانه ادامه دهید، زمانی را به تبدیل استفاده از APIهای منسوخ شده به جایگزین‌های آن‌ها اختصاص دهید، یا به موارد منسوخ شده توجه کنید تا مراقب آن عملکردها باشید و اینکه آیا بعداً حذف می‌شوند یا خیر.

برای شناسایی مشکلات API از lint استفاده کنید

Android lint می‌تواند مشکلات زیادی را در برنامه شما ایجاد کند، از جمله برخی از آنها که نتیجه تغییر نسخه‌های وابستگی یا Android SDK هستند. به عنوان مثال، اگر compileSdk خود را ارتقا دهید و از API های جدید آن استفاده کنید، lint مواردی را که در نسخه های SDK قبلی موجود نیستند گزارش می دهد.

Lint در ویرایشگر Android Studio اجرا می‌شود و با ایجاد تغییرات، مشکلات را گزارش می‌کند. اما معمولاً به عنوان بخشی از ساخت شما در استودیو یا زمانی که یک بیلد خط فرمان را اجرا می‌کنید اجرا نمی‌شود، مگر اینکه از اهداف build یا lint استفاده کنید.

اگر از Continuous Integration (CI) استفاده می‌کنید، gradlew build یا gradlew lint در طول ساخت‌های CI خود (یا حداقل در ساخت‌های شبانه خود) اجرا کنید تا این نوع خطاها را پیدا کنید.

اگر از CI استفاده نمی کنید، حتماً حداقل گاهی اوقات gradlew lint اجرا کنید.

توجه: قوانین لینت در سطح SDK عمومی و Android با AGP ارائه می‌شوند و قوانین خاص کتابخانه با کتابخانه‌های آنها بسته‌بندی می‌شوند. AGP و وابستگی های کتابخانه خود را تا حد امکان به روز نگه دارید تا مطمئن شوید که آخرین قوانین lint در کد شما اعمال می شود. این امر مخصوصاً برای قوانین جدید لینت که برای نسخه جدید Android SDK اضافه یا ارتقا یافته اند بسیار مهم است.

به خطاها و هشدارهای پرز توجه ویژه ای داشته باشید. برخی از کتابخانه‌ها با بررسی‌های لینت مخصوص خود ارسال می‌شوند که به اطمینان از استفاده صحیح از API آنها کمک می‌کند. برخی از نسخه‌های جدید یک کتابخانه شامل هشدارها و خطاهای جدید پرز هستند که در نتیجه هنگام ساخت، گزارش‌های جدیدی ارائه می‌شود.

کاهش خطرات

پس از تعیین خطرات ارتقا، تصمیم بگیرید که چگونه می خواهید آنها را کاهش دهید:

• برخی از خطرات را همانطور که هست بپذیرید. برخی از ریسک ها به اندازه ای کم هستند که قابل قبول باشند، به خصوص زمانی که زمان و منابع به روز رسانی محدود است.
• برخی از خطرات را کاملاً رد کنید. برخی از ارتقاها ممکن است بسیار خطرناک به نظر برسند، به خصوص اگر زمان یا منابع محدودی برای کاهش آنها در این مرحله دارید. اگر نیاز به تریاژ دارید، روی ارتقاهایی تمرکز کنید که برای اشکالاتی که با آن مواجه شده اید یا ویژگی های جدیدی که نیاز دارید، ضروری هستند.
• خطرات باقی مانده را کاهش دهید
  • به‌روزرسانی‌های خود را در مجموعه‌های کوچکتر و مستقل از تغییرات در نظر بگیرید. این امر خطر کلی را کاهش می دهد و امکان بازگشت جزئی را فراهم می کند.
  • تغییرات را با جزئیات بررسی کنید.
  • برنامه خود را برای بررسی تغییرات غیرمنتظره آزمایش کنید . برای ایجاد اطمینان در ارتقاء، در صورت نیاز، آزمایش‌های جدیدی اضافه کنید.
  • هنگامی که مورد مشکوکی یافت شد به منبع (در صورت موجود بودن) نگاه کنید.
  • تغییرات لازم را در منبع یا ساخت خود ایجاد کنید.

تصمیمات خود را مستند کنید اگر خطرات ناشی از ارتقاء هنگام اجرای برنامه شما به مشکل تبدیل شود، مستندسازی تجزیه و تحلیل ریسک شما می تواند تجزیه و تحلیل خطای لازم را کاهش دهد.

اعتبار سنجی مجوزها

توسعه دهندگان کتابخانه مجوز کتابخانه ها را برای استفاده شما صادر می کنند. شما ملزم به رعایت شرایط مجوز هستید وگرنه نمی توانید از کتابخانه استفاده کنید. برخی از مجوزها بسیار مجاز هستند و اغلب فقط به ذکر منبع کتابخانه و ارائه متن مجوز آن به کاربران نهایی نیاز دارند. برخی ویروسی در نظر گرفته می شوند. اگر از آن کتابخانه ها استفاده می کنید، باید همان مجوز را برای برنامه یا کتابخانه خود اعمال کنید.

مجوزها می توانند با هر نسخه ای تغییر کنند. هر زمان که ارتقا می دهید، باید تأیید کنید که وابستگی هایی که استفاده می کنید به روشی سازگار با برنامه یا کتابخانه شما مجوز دارند.

اگر مجوزی سازگار نیست (یا تغییر کرده است که دیگر سازگار نیست)، نمی توانید از آن نسخه کتابخانه استفاده کنید. شما می توانید:

• با صاحب کتابخانه تماس بگیرید و برای ادامه دادن مجوز قدیمی، درخواست ادامه مجوز موجود یا مجوز دوگانه کنید.
• با تیم حقوقی خود کار کنید تا تعیین کنید آیا می توانید مجوز خود را برای سازگاری تغییر دهید.
• کتابخانه دیگری با مجوز سازگار پیدا کنید و برنامه خود را در صورت نیاز اصلاح کنید.
• آخرین نسخه سازگار کتابخانه را فورک کنید (اگر آن مجوز مشتقات را اجازه می دهد و تغییرات عطف به ماسبق نیستند) و تغییرات خود را ایجاد کنید.