إرسال التغييرات التي تم إجراؤها على الرمز

توضّح هذه الصفحة العملية الكاملة لإرسال تغيير الرمز إلى "المشروع المفتوح المصدر لنظام 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 Code Search لعرض رمز مصدر AOSP كما تم تحديده عند استخدامه فعليًا. لمزيد من المعلومات، يُرجى الاطّلاع على بدء استخدام أداة "البحث في الرموز البرمجية". للاطّلاع على كل الرموز البرمجية في فرع main ضمن البحث عن رموز Android، انتقِل إلى https://cs.android.com/android/platform/superproject/main.

  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 Commit.

  4. احفظ الاشتراك.

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

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

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

  1. قم بتشغيل الأمر التالي لتحميل جميع عمليات التنفيذ في جميع مشروعاتك:

    repo upload

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

    .

    يُطلب منك تشغيل نصوص برمجية للجذب.

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

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

    Upload project frameworks/native/ to remote branch main:
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. (اختياري) انقر على 1+ بجانب "إرسال تلقائي" لإرسال التغيير تلقائيًا بعد الحصول على الموافقات. إذا لم تنقر على هذا الزر، يجب على موظف Google إرسال التغيير نيابة عنك.

  5. انقر على إرسال لإرسال التغيير للمراجعة.

يراجع مالكو الرمز التغييرات التي أجريتها على الرمز ويقدم إما ملاحظات لك لحل التغييرات أو الموافقة عليها.

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

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

  • (رمز علامة اختيار): وافق عليه مالك الرمز
  • (رمز متقاطع): لم يوافَق عليه مالك الرمز
  • (رمز الساعة): في انتظار الموافقة من مالك الرمز

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

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

الشكل 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

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

بعد أن يتم إرسال الرمز بنجاح، يجب أن يرسله أحد مراجعي Google الرمز نيابةً عنك. يمكن للمستخدمين الآخرين تشغيل repo sync لعرض التحديث في عملائهم المحلييَن.

بعد دمج المحتوى الذي أرسلته، يمكنك الانتقال إلى لوحة البيانات Android Continuous Integration لتتبُّع عملية دمج المحتوى الذي أرسلته في الشجرة.