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

توضّح هذه الصفحة العملية الكاملة لإرسال تغيير في الرمز البرمجي إلى "مشروع 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 Code Search. يمكنك استخدام "بحث رموز Android" لعرض رمز المصدر الخاص بمشروع AOSP كما يظهر عند استخدامه فعليًا. لمزيد من المعلومات، يُرجى الاطّلاع على بدء استخدام Code Search. للاطّلاع على كل الرموز في أحدث فرع لإصدار 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 android16-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 Continuous Integration لمتابعة عملية دمج مساهماتك في الشجرة.