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

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

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

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

   • اتّبِع أفضل الممارسات الواردة في مقالة تضمين رؤوس التراخيص.

   • بالنسبة إلى رمز Java، اتّبِع نمط رمز Java في AOSP للمشاركين.

   • بعض أجزاء AOSP مكتوبة بلغة Kotlin (.kt)، ويمكنك استخدام Kotlin في أجزاء من النظام الأساسي مكتوبة بلغة Kotlin. لمزيد من المعلومات حول لغة Kotlin في Android، يُرجى الاطّلاع على دليل أسلوب Kotlin المخصّص لمطوّري تطبيقات Android ودليل التشغيل التفاعلي بين Kotlin وJava. للحصول على إرشادات أكثر تفصيلاً حول لغة Kotlin، يُرجى الاطّلاع على موقع لغة Kotlin الإلكتروني.

   • عند كتابة واجهات برمجة التطبيقات، اتّبِع إرشادات واجهة برمجة التطبيقات لنظام التشغيل Android. استخدِم هذه الإرشادات للاطّلاع على السياق الذي تستند إليه قرارات واجهات برمجة التطبيقات في Android. تتحقّق شركة Metalava من صحة الإضافات والتعديلات على واجهات برمجة تطبيقات النظام الأساسي.

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 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، انقر على اقتراح مالكي الملفات:

   

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

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

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

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

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

4. (اختياري) انقر على +1 بجانب "الإرسال التلقائي" لإرسال التغيير تلقائيًا بعد تلقّي الموافقات. إذا لم تنقر على هذا الزر، على أحد موظفي Google إرسال التغيير نيابةً عنك.

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

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

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

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

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

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

الشكل 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 لرصد وقت دمج العينات التي أرسلتها في الشجرة.