این صفحه فرآیند کامل ارسال تغییر کد به پروژه متنباز اندروید (AOSP)، از جمله نحوه درخواست بررسی و پیگیری تغییرات شما را شرح میدهد.
AOSP به Gerrit ، یک سیستم بررسی کد مبتنی بر وب برای پروژههایی که از Git استفاده میکنند، متکی است.
قراردادهای مجوز مشارکتکننده را امضا کنید
قبل از اینکه هرگونه تغییر کد را برای AOSP ارائه دهید، باید توافقنامهها و سربرگهای مجوز Contributor را مطالعه کرده و یکی از توافقنامههای زیر را امضا کنید:
- به عنوان یک مشارکتکنندهی انفرادی که فقط از طرف شما مشارکت میکند، توافقنامهی مجوز مشارکتکنندهی انفرادی را امضا کنید.
- به عنوان کارمندی که برای یک شرکت کار میکند، مطمئن شوید که شرکت شما توافقنامه مجوز مشارکت شرکتی را امضا کرده است که به شما اجازه میدهد از طرف آن مشارکت کنید.
شروع یک شاخه
برای هر تغییر کدی که قصد ایجاد آن را دارید، مراحل زیر را انجام دهید:
یک شاخه جدید را در مخزن گیت مربوطه شروع کنید. یک شاخه کپی از فایلهای اصلی نیست؛ بلکه اشارهگری به یک کامیت خاص است که ایجاد شاخههای محلی و جابجایی بین آنها را به عملیاتی سبک تبدیل میکند. با استفاده از شاخهها، میتوانید تغییرات را از یکدیگر تشخیص دهید. برای شروع یک شاخه، این دستور را اجرا کنید:
repo start BRANCH_NAMEشما میتوانید چندین شاخه مستقل را همزمان در یک مخزن شروع کنید. شاخه BRANCH_NAME محلی در فضای کاری شماست و نه در Gerrit و نه در درخت منبع نهایی گنجانده نشده است. شاخهها همچنین مختص پروژهای هستند که در آن هستید، بنابراین اگر نیاز دارید فایلها را در پروژههای مختلف به عنوان بخشی از یک تغییر تغییر دهید، به یک شاخه در هر پروژه نیاز دارید که در آن فایلها را تغییر دهید.
(اختیاری) تأیید کنید که شاخه ایجاد شده است:
repo status .شما باید شاخهی تازه ایجاد شدهی خود را ببینید. برای مثال:
project frameworks/native/ branch mynewbranch
تغییر خود را ایجاد و آزمایش کنید
برای ایجاد و آزمایش تغییر، این مراحل را دنبال کنید:
برای اطمینان از اینکه با جدیدترین کدبیس کار میکنید، کل کدبیس را همگامسازی کنید:
repo syncاگر در طول همگامسازی با هرگونه تداخلی مواجه شدید، به مراحل ۲ تا ۴ از بخش «حل تداخلهای همگامسازی» مراجعه کنید.
کدی را که باید تغییر دهید پیدا کنید. برای پیدا کردن کد، استفاده از جستجوی کد اندروید را در نظر بگیرید. میتوانید از جستجوی کد اندروید برای مشاهده کد منبع AOSP به شکلی که هنگام استفاده از آن نمایش داده میشود، استفاده کنید. برای اطلاعات بیشتر، به بخش شروع به کار با جستجوی کد مراجعه کنید. برای مشاهده تمام کدهای موجود در آخرین شاخه انتشار AOSP در جستجوی کد اندروید، به آدرس
https://cs.android.com/android/platform/superproject/بروید.فایلهای منبع را تغییر دهید یا اضافه کنید. برای هرگونه تغییر ایجاد شده:
مشخص کنید که آیا نیاز به استفاده از پرچمهای راهاندازی ویژگی دارید یا خیر، و اگر چنین است، آنها را برای کد جدید خود پیادهسازی کنید.
از بهترین شیوههای موجود در بخش «افزودن سربرگهای مجوز» پیروی کنید.
برای کد جاوا، از سبک کد جاوا AOSP برای مشارکتکنندگان پیروی کنید.
برخی از بخشهای AOSP با کاتلین (
.kt) نوشته شدهاند و میتوانید از کاتلین در بخشهایی از پلتفرم که از قبل با کاتلین نوشته شدهاند، استفاده کنید. برای اطلاعات بیشتر در مورد کاتلین در اندروید، به راهنمای سبک کاتلین توسعهدهنده اندروید و راهنمای تعامل کاتلین-جاوا مراجعه کنید. برای راهنماییهای جامعتر کاتلین، به سایت زبان کاتلین مراجعه کنید.هنگام نوشتن APIها، از دستورالعملهای API اندروید پیروی کنید. از این دستورالعملها برای مشاهدهی زمینهی تصمیمات API اندروید استفاده کنید. اضافات و اصلاحات APIهای پلتفرم توسط Metalava تأیید میشوند.
تغییر خود را مرحلهبندی و اعمال کنید
یک کامیت واحد اساسی کنترل ویرایش در گیت است و شامل یک تصویر لحظهای از ساختار دایرکتوری و محتوای فایل برای کل پروژه است. برای کامیت کردن تغییرات خود، این مراحل را دنبال کنید:
به طور پیشفرض، گیت تغییراتی را که شما ایجاد میکنید ثبت میکند اما آنها را ردیابی نمیکند. برای اینکه گیت را مجبور کنید تغییرات شما را ردیابی کند، باید آن تغییرات را برای درج در یک کامیت علامتگذاری یا مرحلهبندی کنید. برای مرحلهبندی تغییر، این دستور را اجرا کنید:
git add -Aاین دستور تغییراتی را که در هر فایلی ایجاد کردهاید، ردیابی میکند.
فایلهای موجود در ناحیهی آمادهسازی را گرفته و آنها را در پایگاه دادهی محلی خود ذخیره یا کامیت کنید:
git commit -sبه طور پیشفرض، یک ویرایشگر متن باز میشود و از شما خواسته میشود که یک پیام کامیت ارائه دهید.
یک پیام کامیت با فرمت زیر ارائه دهید:
خط ۱: عنوان. خلاصهای یک خطی از تغییر ارائه دهید (حداکثر ۵۰ کاراکتر). استفاده از پیشوندها را برای توصیف ناحیهای که تغییر دادهاید در نظر بگیرید و به دنبال آن توضیحی از تغییری که در این کامیت ایجاد کردهاید، مانند مثال زیر که شامل تغییر رابط کاربری است:
ui: Removes deprecated widgetخط ۲: خط خالی. بعد از تیتر، یک خط خالی قرار دهید.
خط ۳: بدنه. توضیحی طولانی و جامع حداکثر ۷۲ کاراکتر ارائه دهید. توضیح دهید که این تغییر چه مشکلی را حل میکند و چگونه. اگرچه بدنه اختیاری است، اما برای دیگران که نیاز به ارجاع به تغییر دارند مفید است. حتماً یادداشتی مختصر از هرگونه فرضیه یا اطلاعات پیشزمینهای که ممکن است هنگام کار مشارکتکننده دیگری روی این ویژگی مهم باشد، درج کنید.
برای خواندن یک وبلاگ در مورد توضیحات خوب برای کامیتها (به همراه مثال)، به نحوه نوشتن پیام کامیت گیت مراجعه کنید.
کامیت را ذخیره کنید.
یک شناسه تغییر منحصر به فرد و نام و ایمیل شما، که در هنگام repo init ارائه شده است، به طور خودکار به پیام commit شما اضافه میشود.
تغییر را برای بررسی آپلود کنید
بعد از اینکه تغییر خود را در تاریخچه شخصی گیت خود ثبت کردید، آن را در Gerrit آپلود کنید:
دستور زیر را برای آپلود تمام کامیتهای خود در تمام پروژههایتان اجرا کنید:
repo uploadتمام تغییرات در تمام پروژهها در فایل آپلود شده لحاظ شده است.
از شما خواسته میشود اسکریپتهای قلاب (hook scripts) را اجرا کنید.
کلید a و سپس Enter را فشار دهید.
از شما خواسته میشود که آپلود را تأیید کنید:
Upload project frameworks/native/ to remote branch android17-release: branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700): ff46b36d android codelab change to https://android-review.googlesource.com/ (y/N)?برای تأیید آپلود، y و سپس Enter را فشار دهید.
شما باید پیامی مشابه remote: SUCCESS دریافت کنید.
درخواست بررسی
پس از آپلود موفقیتآمیز، Repo لینکی به تغییرات شما در Gerrit ارائه میدهد. برای مشاهده تغییرات خود در سرور بررسی، اضافه کردن نظرات یا درخواست بررسی توسط داوران خاص برای تغییر خود، روی لینک کلیک کنید. همه تغییرات در کد باید توسط مالکان کد مربوطه بررسی شود.
برای درخواست بررسی:
در Gerrit، روی پیشنهاد مالکین کلیک کنید:
شکل ۱. لینک مالکان پیشنهادی در Gerrit.
پنجرهی بررسی ظاهر میشود. این پنجره شامل فهرستی از مالکان کد است که میتوانند تغییر شما را بررسی کنند.
برای افزودن مالک کد به بررسی خود، روی او کلیک کنید.
دکمه ارسال (SEND ) فعال میشود.
(اختیاری) آدرس ایمیل هر کس دیگری را که میخواهید تغییر شما را بررسی کند، تایپ کنید.
برای ارسال تغییر جهت بررسی، روی ارسال (SEND) کلیک کنید.
مالکان کد، تغییرات کد شما را بررسی میکنند و در صورت پذیرفته شدن، تغییر را گزینش کرده و آن را در شاخه توسعه داخلی ادغام میکنند.
تعیین وضعیت تغییر
برای تعیین وضعیت فایلهای موجود در تغییر، نمادهای زیر را در کنار فایلهای موجود در تغییر بررسی کنید:
- (آیکون تیک): توسط مالک کد تأیید شده است
- (آیکون ضربدر): توسط مالک کد تأیید نشده است
- (آیکون ساعت): در انتظار تأیید توسط مالک کد
شکل زیر این آیکونهای وضعیت را که در یک تغییر روی فایلها اعمال میشوند، نشان میدهد:
شکل ۲. نمونهای از فایلهایی که آیکونهای آنها تأیید صاحب کد را نشان میدهد.
بازخورد را حل کنید و یک تغییر جایگزین آپلود کنید
اگر یک بررسیکننده درخواست اصلاح بهروزرسانی شما را داشته باشد، میتوانید کامیت خود را در گیت اصلاح کنید که منجر به یک مجموعه وصله جدید برای همان تغییر میشود.
برای حل بازخورد و اصلاح تغییر خود:
مراحل ۲ تا ۴ را در بخش «ایجاد» دنبال کنید و تغییر خود را آزمایش کنید .
برای اصلاح تغییر خود، دستورات زیر را اجرا کنید:
git add -A git commit --amend
وقتی تغییر اصلاحشده را آپلود میکنید، جایگزین تغییر اصلی هم در Gerrit و هم در تاریخچه Git محلی شما میشود.
حل تداخلهای همگامسازی
اگر تغییرات دیگری به درخت منبع ارسال شود که با تغییرات شما مغایرت داشته باشد، پیامی مبنی بر وجود مغایرت دریافت خواهید کرد. برای حل مغایرتها:
مطمئن شوید که با جدیدترین کد کار میکنید:
repo sync .دستور
repo syncبهروزرسانیها را از سرور مبدا دریافت میکند، سپس سعی میکند به طور خودکارHEADشما را رویHEADجدید از راه دور rebase کند.اگر ریبیس خودکار ناموفق بود، ریبیس دستی را انجام دهید:
repo rebase .حل تداخلهای ادغام. اگر روش ترجیحی برای حل تداخلهای ادغام ندارید، میتوانید
git mergetoolبرای رفع دستی تداخلهای بین فایلها استفاده کنید .وقتی فایلهای متناقض را با موفقیت اصلاح کردید، این دستور را برای اعمال کامیتهای جدید اجرا کنید:
git rebase --continue
ارسال تغییر
پس از اینکه یک درخواست از فرآیند بررسی و تأیید عبور کرد، مالک کد، کد را برای شما ارسال میکند، یا در شاخهای که تغییر در آن بررسی شده است یا در یک شاخه داخلی.
پس از ادغام موارد ارسالی، میتوانید از داشبورد ادغام مداوم اندروید (Android Continuous Integration) دیدن کنید تا ببینید چه زمانی موارد ارسالی شما در درختواره ادغام میشوند.