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

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

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

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

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

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

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

    • عند كتابة واجهات برمجة التطبيقات، اتّبِع إرشادات واجهة برمجة التطبيقات Android API. استخدِم هذه الإرشادات للاطّلاع على السياق وراء قرارات واجهة برمجة التطبيقات في 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 android17-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 لتتبُّع وقت دمج عمليات الإرسال في الشجرة.