إرسال تغييرات الرمز

توضّح هذه الصفحة العملية الكاملة لإرسال تغيير في الرمز البرمجي إلى "المشروع المفتوح المصدر لنظام Android" ‏ (AOSP)، بما في ذلك كيفية طلب إجراء مراجعة وتتبُّع التغييرات التي أجريتها.

يعتمد AOSP على Gerrit، وهو نظام مراجعة رموز برمجية على الويب للمشاريع التي تستخدم Git.

توقيع اتفاقيات ترخيص المساهمين

قبل المساهمة بأي تغييرات على الرموز البرمجية في AOSP، عليك قراءة اتّفاقيات التراخيص والمخطّطات الرئيسية للمشاركين وتوقيع إحدى الاتفاقيات التالية:

بدء فرع

لكلّ تغيير في الرمز تريد إجراؤه، اتّبِع الخطوات التالية:

  1. ابدأ فرعًا جديدًا ضمن مستودع Git ذي الصلة. الفروع ليست نسخة من الملفات الأصلية، بل هي مؤشر إلى عملية إرسال محددة، ما يجعل إنشاء الفروع المحلية والتبديل بينها عملية سهلة. من خلال استخدام الفروع، يمكنك تحديد التغييرات عن بعضها. شغِّل هذا الأمر لبدء فرع:

    repo start BRANCH_NAME

    يمكنك بدء عدة فروع مستقلة في الوقت نفسه في المستودع نفسه. الفرع BRANCH_NAME هو فرع محلي في مساحة العمل ولا يتم تضمينه في Gerrit أو في شجرة المصدر النهائية. تكون الفروع أيضًا خاصة بالمشروع الذي تعمل عليه، لذا إذا كنت بحاجة إلى تغيير الملفات في مشاريع مختلفة كجزء من التغيير نفسه، ستحتاج إلى فرع في كل مشروع تغيّر فيه الملفات.

  2. (اختياري) تأكَّد من إنشاء الفرع:

    repo status .

    من المفترض أن يظهر لك الفرع الذي تم إنشاؤه حديثًا. مثلاً:

    project frameworks/native/                      branch mynewbranch

إجراء التغيير واختباره

اتّبِع الخطوات التالية لإجراء التغيير واختباره:

  1. لضمان استخدام أحدث قاعدة بيانات، يمكنك مزامنة قاعدة البيانات بأكملها:

    repo sync

    إذا واجهت أي تعارضات أثناء المزامنة، راجِع الخطوات من 2 إلى 4 في مقالة حلّ تعارضات المزامنة.

  2. ابحث عن الرمز المطلوب تغييره. للعثور على الرمز، ننصحك باستخدام بحث الرموز على Android. يمكنك استخدام أداة "بحث رمز Android" لعرض رمز المصدر في AOSP كما هو موضّح عند استخدامه. لمزيد من المعلومات، يُرجى الاطّلاع على البدء في استخدام ميزة "بحث الرموز البرمجية". للاطّلاع على كل الرمز البرمجي في أحدث فرع لإصدار AOSP ضمن "بحث الرمز البرمجي" في Android، انتقِل إلى https://cs.android.com/android/platform/superproject/.

  3. تعديل الملفات المصدر أو إضافتها في ما يتعلّق بأي تغييرات تم إجراؤها:

  4. إنشاء نظام التشغيل Android

  5. اختبار الإصدار

إعداد التغيير وتأكيده

الترميز هو الوحدة الأساسية للتحكّم في المراجعات في Git، ويتكوّن من لقطة شاشة لبنية الدليل ومحتوى الملفات للمشروع بأكمله. اتّبِع الخطوات التالية لحفظ التغيير:

  1. يُسجِّل Git التغييرات التي تجريها تلقائيًا، ولكنه لا يتتبّعها. لتوجيه Git لتتبُّع التغييرات، عليك وضع علامة على هذه التغييرات أو وضعها في مرحلة معيّنة لتضمينها في عملية تسجيل. شغِّل هذا الأمر لطرح التغيير:

    git add -A

    يتتبّع هذا الأمر التغييرات التي أجريتها على أي ملفات.

  2. استخدِم الملفات في منطقة الإعداد واحفظها في ملفاتك المحلية أو أرسِلها:

    git commit -s

    يتم تلقائيًا فتح محرِّر نصوص ويُطلب منك تقديم رسالة تأكيد.

  3. قدِّم رسالة التزام بالتنسيق التالي:

    • السطر 1: العنوان قدِّم ملخّصًا في سطر واحد للتغيير (50 حرفًا كحدّ أقصى). ننصحك باستخدام البادئات لوصف الجزء الذي أجريت تغييرات عليه، متبوعًا بوصف للتغيير الذي أجريته في هذا الإصدار، مثل المثال التالي الذي يتضمّن تغييرًا في واجهة المستخدم:

      ui: Removes deprecated widget

    • السطر 2: سطر فارغ أضِف سطرًا فارغًا بعد العنوان.

    • السطر 3: النص قدِّم وصفًا طويلاً يتم اقتطاعه عند 72 حرفًا بحد أقصى. يُرجى وصف المشكلة التي يحلّها التغيير وكيفية حلّها. على الرغم من أنّ النصّ هو اختياري، إلا أنّه مفيد للمستخدمين الآخرين الذين يحتاجون إلى الرجوع إلى التغيير. احرص على تضمين ملاحظة موجزة عن أي افتراضات أو معلومات أساسية قد تكون مهمة عندما يعمل مساهم آخر على هذه الميزة.

    لقراءة مدوّنة عن أوصاف المراجعات الجيدة (مع أمثلة)، يُرجى الاطّلاع على كيفية كتابة رسالة مراجعة في Git.

  4. احفظ عملية الربط.

تتم تلقائيًا إضافة معرّف تغيير فريد واسمك وبريدك الإلكتروني، اللذان تم تقديمهما أثناء repo init، إلى رسالة الإضافة.

تحميل التغيير للمراجعة

بعد تأكيد التغيير في سجلّ Git الشخصي، حمِّله إلى Gerrit:

  1. نفِّذ الأمر التالي لتحميل جميع عمليات الربط في كل مشاريعك:

    repo upload

    يتم تضمين جميع التغييرات في جميع المشاريع في عملية التحميل.

    .

    سيُطلب منك تشغيل نصوص الربط.

  2. اضغط على a ثم على Enter.

    سيُطلب منك الموافقة على عملية التحميل:

    Upload project frameworks/native/ to remote branch android15-qpr2-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)?

  3. اضغط على y ثم على Enter للموافقة على التحميل.

من المفترض أن تصلك رسالة مشابهة للرسالة remote: SUCCESS.

طلب إجراء مراجعة

بعد تحميل التغييرات بنجاح، يقدّم لك Repo رابطًا يؤدي إلى التغييرات في Gerrit. انقر على الرابط لعرض التغييرات على خادم المراجعة أو إضافة تعليقات أو طلب مراجعين محدّدين للتغيير. يجب أن يراجع مالكو الرموز البرمجية المناسبون جميع التغييرات التي يتم إجراؤها على الرمز.

لطلب إجراء مراجعة، يُرجى اتّباع الخطوات التالية:

  1. في Gerrit، انقر على اقتراح مالكي الملفات:

    اقتراح رابط المالكين في Gerrit

    الشكل 1: اقتراح رابط مالكي الإصدارات في Gerrit

    يظهر مربّع حوار المُراجع. يحتوي مربّع الحوار هذا على قائمة بأصحاب الرموز البرمجية الذين يمكنهم مراجعة التغيير الذي أجريته.

  2. انقر على مالك رمز لإضافة مراجعته إلى مراجعتك.

    تم تفعيل الزر إرسال.

  3. (اختياري) اكتب عنوان البريد الإلكتروني لأي مستخدم آخر تريد أن يراجع التغيير.

  4. انقر على إرسال لإرسال التغيير لمراجعته.

يراجع مالكو الرموز البرمجية تغييرات الرموز البرمجية، وفي حال قبولها، يختارون التغيير ويدمجونه في فرع التطوير الداخلي.

تحديد حالة التغيير

لتحديد حالة الملفات في التغيير، ابحث عن الرموز التالية بجانب الملفات في التغيير:

  • (رمز علامة اختيار ): تمت الموافقة عليه من قِبل مالك الرمز
  • (رمز الصليب): لم يوافق مالك الرمز على ذلك
  • (رمز الساعة ): في انتظار موافقة مالك الرمز

يعرض الشكل التالي رموز الحالة هذه المطبَّقة على الملفات في التغيير:

مثال على الملفات التي تحتوي على رموز تُظهر موافقة مالك الرمز البرمجي

الشكل 2: مثال على ملفات تتضمّن رموزًا توضّح موافقة مالك الرمز البرمجي

حلّ الملاحظات وتحميل تغيير بديل

إذا طلب أحد المراجعين إجراء تعديل على التعديل، يمكنك تعديل عملية الإضافة ضمن Git، ما يؤدي إلى إنشاء مجموعة تصحيحات جديدة للتغيير نفسه.

لحلّ الملاحظات وتعديل التغيير:

  1. اتّبِع الخطوات من 2 إلى 4 في إجراء التغيير واختباره.

  2. شغِّل الأوامر التالية لتعديل التغيير:

    git add -A
git commit --amend

  3. حمِّل التغيير.

عند تحميل التغيير المعدَّل، سيحلّ محل التغيير الأصلي في كلّ من Gerrit وسجلّ Git المحلي.

حلّ تعارضات المزامنة

إذا تم إرسال تغييرات أخرى إلى شجرة المصدر تتعارض مع التغييرات التي أجريتها، ستتلقّى رسالة تفيد بوجود تعارضات. لحلّ التعارضات:

  1. تأكَّد من استخدام أحدث رمز:

    repo sync .

    يُستخدَم الأمر repo sync لجلب التعديلات من الخادم المصدر، ثم محاولة إعادة ربط HEAD تلقائيًا بـ HEAD البعيد الجديد.

  2. إذا تعذّرت إعادة الربط التلقائية، يمكنك إجراء إعادة ربط يدويًا:

    repo rebase .

  3. حلّ تعارضات الدمج إذا لم تكن لديك طريقة مفضّلة لحلّ تعارضات الدمج، يمكنك استخدام git mergetool لحلّ التعارضات بين الملفات يدويًا.

  4. بعد إصلاح الملفات المتضاربة بنجاح، نفِّذ هذا الأمر لتطبيق عمليات الإضافة الجديدة:

    git rebase --continue

إرسال التغيير

بعد أن يجتاز الرمز عملية المراجعة والتحقّق، يرسله مالك الرمز نيابةً عنك، إما في الفرع الذي تمت فيه مراجعة التغيير أو في فرع داخلي.

بعد دمج العينة التي أرسلتها، يمكنك الانتقال إلى لوحة بيانات الدمج المستمر لنظام التشغيل Android لرصد عمليات دمج العينات التي أرسلتها في الشجرة.