ارسال پچ ها

این صفحه روند کامل ارسال یک وصله به پروژه منبع باز Android (AOSP) را شرح می‌دهد، از جمله نحوه درخواست بازبینی و ردیابی تغییرات خود با Gerrit .

پیش نیازها

برای شروع، مطمئن شوید که کارهای زیر را انجام داده اید:

منابع

  • برای جزئیات در مورد Repo و Git، به صفحه Source Control Tools مراجعه کنید.
  • برای کسب اطلاعات در مورد نقش های مختلف در جامعه متن باز Android، به صفحه نقش های پروژه مراجعه کنید.
  • برای اطلاعات مجوز درباره مشارکت کد در پلتفرم Android، به صفحه مجوزها مراجعه کنید.

برای مشارکت کنندگان

احراز هویت با سرور

اگر یک آدرس IP را با سایر کاربران به اشتراک بگذارید، سهمیه ها می توانند حتی برای الگوهای استفاده معمولی فعال شوند. این ممکن است زمانی اتفاق بیفتد که، برای مثال، بسیاری از کاربران، مشتریان جدید را از همان آدرس IP در مدت زمان کوتاهی همگام‌سازی کنند. دسترسی احراز هویت شده از یک سهمیه جداگانه برای هر کاربر صرف نظر از آدرس IP استفاده می کند. برای مطالعه در مورد فعال کردن دسترسی تأیید شده، به استفاده از احراز هویت مراجعه کنید.

راه اندازی شعبه Repo

برای هر تغییری که قصد انجام آن را دارید، یک شاخه جدید در مخزن Git مربوطه راه اندازی کنید:

repo start NAME .

می توانید چندین شعبه مستقل را همزمان در یک مخزن راه اندازی کنید. شاخه NAME محلی برای فضای کاری شما است و نه در Gerrit و نه در درخت منبع نهایی گنجانده نشده است.

ایجاد تغییر شما

فایل های منبع را تغییر دهید و تغییرات خود را تأیید کنید.

با این دستورات تغییرات را در مخزن محلی خود انجام دهید:

git add -A
git commit -s

تغییر توضیحات

  • خط 1: عنوان

    ارائه خلاصه یک خطی ( حداکثر 50 کاراکتر)

    این فرمت توسط Git و Gerrit برای نمایشگرهای مختلف استفاده می شود. این مهم ترین و متراکم ترین بخش پیام تعهد شماست. استفاده از پیشوندهایی را برای توصیف ناحیه ای که تغییر داده اید، در نظر بگیرید، به دنبال آن تغییراتی را که در این commit ایجاد کرده اید، توضیح دهید، مانند این که پیشوند ui دارد:

    ui: Removes deprecated widget

  • خط 2: خالی

    این خط را همیشه خالی نگه دارید.

  • خط 3: بدن

    شرح طولانی تری بنویسید، از این خط شروع کنید.

    این باید با حداکثر 72 کاراکتر بسته بندی شود. توضیح دهید که این تغییر چه مشکلی را حل می کند و چگونه. اگرچه این امر هنگام اجرای ویژگی‌های جدید اختیاری است، اما اگر بعداً دیگران به این تغییر مراجعه کنند، مخصوصاً برای اشکال‌زدایی، بسیار مفید است.

    یک یادداشت مختصر از هرگونه فرضیات یا اطلاعات پس‌زمینه‌ای که ممکن است زمانی که مشارکت‌کننده دیگری روی این ویژگی کار می‌کند مهم باشد، اضافه کنید.

یک شناسه تغییر منحصربه‌فرد و نام و ایمیل شما، که در هنگام repo init ارائه می‌شوند، به‌طور خودکار به پیام commit شما اضافه می‌شوند.

در اینجا یک نمونه پیام commit آمده است:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
برای خواندن یک وبلاگ در مورد توضیحات commit خوب (با مثال)، به نحوه نوشتن یک پیام Git Commit توسط کریس بیمز مراجعه کنید.

در حال آپلود در Gerrit

پس از اینکه تغییر خود را در تاریخچه شخصی خود انجام دادید، آن را با این دستور در Gerrit آپلود کنید:

repo upload

اگر چندین شعبه را در یک مخزن راه اندازی کرده اید، از شما خواسته می شود انتخاب کنید کدام یک را آپلود کنید.

پس از آپلود موفقیت آمیز، Repo URL یک صفحه جدید در Gerrit را در اختیار شما قرار می دهد. روی پیوندی که Repo به شما می دهد کلیک کنید تا پچ خود را در سرور بررسی مشاهده کنید، نظرات خود را اضافه کنید یا از بازبینان خاصی برای وصله خود درخواست کنید.

درخواست بررسی

پس از اینکه تغییرات خود را در Gerrit آپلود کردید، پچ باید توسط صاحبان کد مربوطه بررسی و تایید شود. صاحبان کد را در فایل های OWNERS پیدا کنید.

برای پیدا کردن صاحبان کد مناسب و اضافه کردن آنها به عنوان بازبین برای تغییر خود، این مراحل را دنبال کنید.

  1. پیوند SUGGEST OWNERS را در Gerrit UI انتخاب کنید تا فهرستی از مالکان کد فایل‌های موجود در پچ خود را ببینید.

    لینک مالکان را در Gerrit پیشنهاد کنید
    شکل 1. پیوند مالکان را در Gerrit پیشنهاد دهید

  2. صاحبان کد را از لیست به عنوان بازبین برای پچ خود اضافه کنید.

برای تعیین وضعیت فایل‌های پچ، نمادهای زیر را در کنار فایل‌های پچ بررسی کنید.

  • (نماد علامت): تایید شده توسط صاحب کد
  • (نماد متقاطع): توسط مالک کد تایید نشده است
  • (نماد ساعت): در انتظار تایید توسط مالک کد
شکل 2. نمونه فایل هایی با نمادهایی که وضعیت تایید مالک کد را نشان می دهد

آپلود پچ جایگزین

فرض کنید یک بازبینی کننده به پچ شما نگاه کرده و یک تغییر کوچک درخواست کرده است. می‌توانید commit خود را در Git اصلاح کنید، که منجر به ایجاد یک پچ جدید در Gerrit می‌شود که همان شناسه تغییر نسخه اصلی را دارد.

git add -A
git commit --amend

وقتی پچ اصلاح شده را آپلود می کنید، هم در Gerrit و هم در تاریخچه Git محلی شما جایگزین نسخه اصلی می شود.

حل تعارضات همگام سازی

اگر وصله های دیگری به درخت منبع ارسال شد که با شما در تضاد است، وصله خود را در بالای HEAD جدید مخزن منبع تغییر دهید. برای انجام این کار، این دستور را اجرا کنید:

repo sync

دستور repo sync به‌روزرسانی‌ها را از سرور منبع دریافت می‌کند، سپس سعی می‌کند به طور خودکار HEAD شما را روی HEAD از راه دور جدید تغییر دهد.

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

repo rebase

ابزار دیگری برای مقابله با تضاد rebase git mergetool است. هنگامی که فایل های متناقض را با موفقیت ادغام کردید، این دستور را اجرا کنید:

git rebase --continue

پس از تکمیل تغییر خودکار یا دستی، repo upload اجرا کنید تا پچ تغییر یافته خود را ارسال کنید.

پس از تایید یک ارسال

پس از اینکه یک ارسال از طریق فرآیند بررسی و تأیید انجام شد، Gerrit به طور خودکار تغییر را در مخزن عمومی ادغام می کند. سایر کاربران می توانند repo sync اجرا کنند تا به روز رسانی را به مشتریان محلی مربوطه خود بکشند.

برای پروژه های بالادستی

Android از تعدادی پروژه منبع باز دیگر، مانند هسته لینوکس و WebKit، همانطور که در مدیریت نرم افزار اندروید توضیح داده شده است، استفاده می کند. برای اکثر پروژه هایی که تحت external/ قرار دارند، تغییرات را در بالادست انجام دهید، سپس نگهبانان Android را از نسخه جدید بالادستی که حاوی تغییرات شما است مطلع کنید.

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

یک مورد خاص جالب Bionic است. بسیاری از کدهای موجود از BSD هستند، بنابراین، مگر اینکه تغییر به کدهایی باشد که برای Bionic جدید هستند، لطفاً یک اصلاح بالادستی انجام دهید، سپس یک فایل کاملاً جدید را از BSD مناسب بکشید.

هسته اندروید

همه تغییرات را در بالادست انجام دهید. برای راهنمایی کلی، دستورالعمل‌های مشارکت هسته Android و صفحه توسعه کد هسته برای GKI را دنبال کنید.

آی سی یو

همه تغییرات را در پروژه ICU در external/icu (پوشه icu4c/ و icu4j/ ) در صفحه اصلی ICU-TC انجام دهید. برای اطلاعات بیشتر به ارسال اشکالات ICU و درخواست های ویژگی مراجعه کنید.

CLDR

بیشتر داده های زبانی در ICU از پروژه Unicode CLDR می آید. لطفاً همه درخواست‌ها را با استفاده از درخواست‌های تغییر CLDR ارسال کنید و برچسب «Android» را اضافه کنید.

LLVM/Clang/Compiler-rt

همه تغییرات را در پروژه های مرتبط با LLVM ( external/clang ، external/compiler-rt ، external/llvm ) در صفحه زیرساخت کامپایلر LLVM انجام دهید.

mksh

همه تغییرات را در پروژه MirBSD Korn Shell در external/mksh یا با ارسال ایمیل به miros-mksh در دامنه mirbsd.org (بدون نیاز به اشتراک برای ارسال در آنجا) یا در Launchpad انجام دهید.

OpenSSL

همه تغییرات را در پروژه OpenSSL در external/openssl در صفحه OpenSSL انجام دهید.

V8

همه تغییرات پروژه V8 را در external/v8 در صفحه شماره V8 ارسال کنید. برای جزئیات بیشتر به مشارکت در V8 مراجعه کنید.

وب کیت

همه تغییرات را در پروژه WebKit در external/webkit در صفحه WebKit انجام دهید. فرآیند را با پر کردن یک باگ WebKit شروع کنید. در باگ، تنها در صورتی از Android برای فیلدهای پلتفرم و سیستم عامل استفاده کنید که باگ مخصوص اندروید باشد. پس از اضافه شدن یک اصلاح پیشنهادی و گنجاندن آزمایش‌ها، احتمال بیشتری وجود دارد که اشکالات توجه بازبینان را جلب کنند. برای جزئیات بیشتر به مشارکت کد در WebKit مراجعه کنید.

zlib

همه تغییرات را در پروژه zlib در external/zlib در صفحه اصلی zlib انجام دهید.