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

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

3. تعديل الملفات المصدر أو إضافتها بالنسبة إلى أي تغييرات تم إجراؤها:

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

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

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

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

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

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