ارسال پچ ها

این صفحه روند کامل ارسال یک وصله به پروژه منبع باز 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/ قرار دارند، تغییرات را در بالادست انجام دهید، سپس نگهبانان اندروید را از نسخه جدید بالادستی که حاوی تغییرات شماست مطلع کنید.

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

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

هسته اندروید

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

آی سی یو

همه تغییرات را در پروژه 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 انجام دهید.