ارسال پچ ها

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

پیش نیازها

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

منابع

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

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

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

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

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

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

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Making your change

Modify the source files, and validate your changes.

Commit the changes to your local repository with these commands:

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.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Uploading to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command: 

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Requesting a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit

  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Uploading a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original. 

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 و درخواست های ویژگی مراجعه کنید. برچسب «اندروید» را به همه درخواست‌های بالادست Jira اضافه کنید.

CLDR

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

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 انجام دهید.