إرسال بقع

توضح هذه الصفحة العملية الكاملة لإرسال التصحيح إلى مشروع Android مفتوح المصدر (AOSP)، بما في ذلك كيفية طلب مراجعة وتتبع تغييراتك باستخدام Gerrit . Gerrit هو نظام مراجعة التعليمات البرمجية على شبكة الإنترنت للمشاريع التي تستخدم Git. يشجع Gerrit على استخدام Git بشكل أكثر مركزية من خلال السماح لجميع المستخدمين المعتمدين بإرسال التغييرات، والتي يتم دمجها تلقائيًا إذا اجتازوا مراجعة التعليمات البرمجية. بالإضافة إلى ذلك، يعمل Gerrit على تسهيل المراجعة، وعرض التغييرات جنبًا إلى جنب في المتصفح وتمكين التعليقات المضمنة.

المتطلبات الأساسية

للبدء، تأكد من قيامك بما يلي:

موارد

  • للحصول على تفاصيل حول Repo وGit، راجع صفحة أدوات التحكم في المصدر .
  • للحصول على معلومات حول الأدوار المختلفة داخل مجتمع Android مفتوح المصدر، راجع صفحة أدوار المشروع .
  • للحصول على معلومات الترخيص حول المساهمة بالتعليمات البرمجية في نظام Android الأساسي، راجع صفحة التراخيص .

تكوين جيت

لاستخدام Gerrit، يجب أن يكون بريدك الإلكتروني مرتبطًا بحساب Google مسجل. قم بتشغيل الأوامر التالية لتكوين Git بالاسم وعنوان البريد الإلكتروني المرتبط بحساب Google المسجل:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

المصادقة مع الخادم

إذا كنت تشارك عنوان IP مع مستخدمين آخرين، فيمكن تفعيل الحصص حتى بالنسبة لأنماط الاستخدام العادية. يمكن أن يحدث هذا، على سبيل المثال، عندما يقوم العديد من المستخدمين بمزامنة عملاء جدد من نفس عنوان IP خلال فترة زمنية قصيرة. يستخدم الوصول المصادق حصة نسبية منفصلة لكل مستخدم، بغض النظر عن عنوان IP. لقراءة حول تنشيط الوصول المصادق عليه، راجع استخدام المصادقة .

بدء فرع الريبو

لكل تغيير تنوي إجراؤه، ابدأ فرعًا جديدًا داخل مستودع Git ذي الصلة:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

تغيير الأوصاف

  • السطر 1: العنوان

    تقديم ملخص من سطر واحد (50 حرفًا كحد أقصى )

    يتم استخدام هذا التنسيق بواسطة Git وGerrit لشاشات العرض المختلفة. إنه الجزء الأكثر أهمية والأكثر كثافة في رسالة الالتزام الخاصة بك. فكر في استخدام البادئات لوصف المنطقة التي قمت بتغييرها، متبوعة بوصف التغيير الذي أجريته في هذا الالتزام، مثل هذا التغيير الذي يحتوي على ui كبادئة:

    ui: Removes deprecated widget

  • السطر 2: فارغ

    أبقِ هذا السطر فارغًا دائمًا.

  • السطر 3: الجسم

    اكتب وصفًا أطول، بدءًا من هذا السطر.

    يجب أن يكون هذا ملتفًا بحد أقصى 72 حرفًا. قم بوصف المشكلة التي يحلها التغيير وكيف. على الرغم من أن هذا يعد اختياريًا عند تنفيذ ميزات جديدة، إلا أنه من المفيد جدًا للآخرين لاحقًا إذا أشاروا إلى هذا التغيير، خاصة فيما يتعلق بتصحيح الأخطاء.

    قم بتضمين ملاحظة مختصرة عن أي افتراضات أو معلومات أساسية قد تكون مهمة عندما يعمل مساهم آخر على هذه الميزة.

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

فيما يلي مثال لرسالة الالتزام:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

عندما تقوم بتحميل التصحيح المعدل، فإنه يحل محل التصحيح الأصلي في Gerrit وفي سجل Git المحلي لديك.

حل تعارضات المزامنة

إذا تم إرسال تصحيحات أخرى إلى الشجرة المصدر التي تتعارض مع التصحيح الخاص بك، فأعد تثبيت التصحيح الخاص بك أعلى HEAD الجديد لمستودع المصدر. للقيام بذلك، قم بتشغيل هذا الأمر:

repo sync

يقوم أمر repo sync بجلب التحديثات من الخادم المصدر، ثم يحاول إعادة وضع HEAD تلقائيًا على HEAD البعيد الجديد.

إذا لم تنجح عملية إعادة الأساس التلقائي، فقم بإجراء عملية إعادة الأساس يدويًا.

repo rebase

هناك أداة أخرى للتعامل مع تعارض إعادة الأساس وهي git mergetool . عند دمج الملفات المتعارضة بنجاح، قم بتشغيل هذا الأمر:

git rebase --continue

بعد اكتمال عملية إعادة الأساس التلقائية أو اليدوية، قم بتشغيل repo upload لإرسال التصحيح المُعاد تأسيسه.

بعد الموافقة على التقديم

بعد أن يمر الإرسال بعملية المراجعة والتحقق، يقوم Gerrit تلقائيًا بدمج التغيير في المستودع العام. يمكن للمستخدمين الآخرين تشغيل repo sync لسحب التحديث إلى عملائهم المحليين.

للمشاريع المنبع

يستخدم Android عددًا من المشاريع الأخرى مفتوحة المصدر، مثل Linux kernel وWebKit، كما هو موضح في إدارة برامج Android . بالنسبة لمعظم المشاريع الموجودة ضمن external/ ، قم بإجراء التغييرات في المنبع، ثم قم بإبلاغ مشرفي Android بالإصدار الجديد الذي يحتوي على تغييراتك.

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

إحدى الحالات الخاصة المثيرة للاهتمام هي Bionic. معظم التعليمات البرمجية الموجودة موجودة من BSD، لذا ما لم يكن التغيير على تعليمات برمجية جديدة في Bionic، فيرجى إجراء إصلاح أولي، ثم سحب ملف جديد بالكامل من BSD المناسب.

نواة أندرويد

قم بإجراء جميع التغييرات في المنبع. للحصول على إرشادات عامة، اتبع إرشادات مساهمة Android Kernel وصفحة تطوير Kernel Code لـ GKI .

وحدة العناية المركزة

قم بإجراء كافة التغييرات على مشروع ICU في المجلدات external/icu ( icu4c/ و icu4j/ ) على الصفحة الرئيسية لـ ICU-TC . راجع إرسال أخطاء وحدة العناية المركزة وطلبات الميزات للمزيد. أضف التصنيف "android" إلى جميع طلبات Jira الأولية.

كلدر

معظم البيانات اللغوية في وحدة العناية المركزة تأتي من مشروع Unicode CLDR . أرسل جميع الطلبات إلى المنبع وفقًا للمساهمة في CLDR وأضف التصنيف "android".

LLVM/Clang/المترجم-rt

قم بإجراء كافة التغييرات على المشاريع المتعلقة بـ LLVM ( external/clang , external/compiler-rt , external/llvm ) على صفحة البنية التحتية للمترجم LLVM .

mksh

قم بإجراء جميع التغييرات على مشروع MirBSD Korn Shell على external/mksh إما عن طريق إرسال بريد إلكتروني إلى miros-mksh على المجال mirbsd.org (لا يلزم الاشتراك للإرسال هناك) أو على Launchpad .

OpenSSL

قم بإجراء كافة التغييرات على مشروع OpenSSL في external/openssl على صفحة OpenSSL .

V8

قم بإرسال كافة التغييرات إلى مشروع V8 على external/v8 في صفحة إصدار V8 . راجع المساهمة في V8 للحصول على التفاصيل.

WebKit

قم بإجراء جميع التغييرات على مشروع WebKit على external/webkit على صفحة WebKit . ابدأ العملية عن طريق تقديم خطأ WebKit . في الخطأ، استخدم حقول Android للنظام الأساسي ونظام التشغيل فقط إذا كان الخطأ خاصًا بنظام Android. من المرجح أن تحظى الأخطاء باهتمام المراجعين بعد إضافة الإصلاح المقترح وتضمين الاختبارات. راجع المساهمة بالكود في WebKit للحصول على التفاصيل.

زليب

قم بإجراء جميع التغييرات على مشروع zlib على external/zlib على صفحة zlib الرئيسية .

,

توضح هذه الصفحة العملية الكاملة لإرسال التصحيح إلى مشروع Android مفتوح المصدر (AOSP)، بما في ذلك كيفية طلب مراجعة وتتبع تغييراتك باستخدام Gerrit . Gerrit هو نظام مراجعة التعليمات البرمجية على شبكة الإنترنت للمشاريع التي تستخدم Git. يشجع Gerrit على استخدام Git بشكل أكثر مركزية من خلال السماح لجميع المستخدمين المعتمدين بإرسال التغييرات، والتي يتم دمجها تلقائيًا إذا اجتازوا مراجعة التعليمات البرمجية. بالإضافة إلى ذلك، يعمل Gerrit على تسهيل المراجعة، وعرض التغييرات جنبًا إلى جنب في المتصفح وتمكين التعليقات المضمنة.

المتطلبات الأساسية

للبدء، تأكد من قيامك بما يلي:

موارد

  • للحصول على تفاصيل حول Repo وGit، راجع صفحة أدوات التحكم في المصدر .
  • للحصول على معلومات حول الأدوار المختلفة داخل مجتمع Android مفتوح المصدر، راجع صفحة أدوار المشروع .
  • للحصول على معلومات الترخيص حول المساهمة بالتعليمات البرمجية في نظام Android الأساسي، راجع صفحة التراخيص .

تكوين جيت

لاستخدام Gerrit، يجب أن يكون بريدك الإلكتروني مرتبطًا بحساب Google مسجل. قم بتشغيل الأوامر التالية لتكوين Git بالاسم وعنوان البريد الإلكتروني المرتبط بحساب Google المسجل:

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

المصادقة مع الخادم

إذا كنت تشارك عنوان IP مع مستخدمين آخرين، فيمكن تفعيل الحصص حتى بالنسبة لأنماط الاستخدام العادية. يمكن أن يحدث هذا، على سبيل المثال، عندما يقوم العديد من المستخدمين بمزامنة عملاء جدد من نفس عنوان IP خلال فترة زمنية قصيرة. يستخدم الوصول المصادق حصة نسبية منفصلة لكل مستخدم، بغض النظر عن عنوان IP. لقراءة حول تنشيط الوصول المصادق عليه، راجع استخدام المصادقة .

بدء فرع الريبو

لكل تغيير تنوي إجراؤه، ابدأ فرعًا جديدًا داخل مستودع Git ذي الصلة:

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

تغيير الأوصاف

  • السطر 1: العنوان

    تقديم ملخص من سطر واحد (50 حرفًا كحد أقصى )

    يتم استخدام هذا التنسيق بواسطة Git وGerrit لشاشات العرض المختلفة. إنه الجزء الأكثر أهمية والأكثر كثافة في رسالة الالتزام الخاصة بك. فكر في استخدام البادئات لوصف المنطقة التي قمت بتغييرها، متبوعة بوصف التغيير الذي أجريته في هذا الالتزام، مثل هذا التغيير الذي يحتوي على ui كبادئة:

    ui: Removes deprecated widget

  • السطر 2: فارغ

    أبقِ هذا السطر فارغًا دائمًا.

  • السطر 3: الجسم

    اكتب وصفًا أطول، بدءًا من هذا السطر.

    يجب أن يكون هذا ملتفًا بحد أقصى 72 حرفًا. قم بوصف المشكلة التي يحلها التغيير وكيف. على الرغم من أن هذا يعد اختياريًا عند تنفيذ ميزات جديدة، إلا أنه من المفيد جدًا للآخرين لاحقًا إذا أشاروا إلى هذا التغيير، خاصة فيما يتعلق بتصحيح الأخطاء.

    قم بتضمين ملاحظة مختصرة عن أي افتراضات أو معلومات أساسية قد تكون مهمة عندما يعمل مساهم آخر على هذه الميزة.

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

فيما يلي مثال لرسالة الالتزام:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

عندما تقوم بتحميل التصحيح المعدل، فإنه يحل محل التصحيح الأصلي في Gerrit وفي سجل Git المحلي لديك.

حل تعارضات المزامنة

إذا تم إرسال تصحيحات أخرى إلى الشجرة المصدر التي تتعارض مع التصحيح الخاص بك، فأعد تثبيت التصحيح الخاص بك أعلى HEAD الجديد لمستودع المصدر. للقيام بذلك، قم بتشغيل هذا الأمر:

repo sync

يقوم أمر repo sync بجلب التحديثات من الخادم المصدر، ثم يحاول إعادة وضع HEAD تلقائيًا على HEAD البعيد الجديد.

إذا لم تنجح عملية إعادة الأساس التلقائي، فقم بإجراء عملية إعادة الأساس يدويًا.

repo rebase

هناك أداة أخرى للتعامل مع تعارض إعادة الأساس وهي git mergetool . عند دمج الملفات المتعارضة بنجاح، قم بتشغيل هذا الأمر:

git rebase --continue

بعد اكتمال عملية إعادة الأساس التلقائية أو اليدوية، قم بتشغيل repo upload لإرسال التصحيح المُعاد تأسيسه.

بعد الموافقة على التقديم

بعد أن يمر الإرسال بعملية المراجعة والتحقق، يقوم Gerrit تلقائيًا بدمج التغيير في المستودع العام. يمكن للمستخدمين الآخرين تشغيل repo sync لسحب التحديث إلى عملائهم المحليين.

للمشاريع المنبع

يستخدم Android عددًا من المشاريع الأخرى مفتوحة المصدر، مثل Linux kernel وWebKit، كما هو موضح في إدارة برامج Android . بالنسبة لمعظم المشاريع الموجودة ضمن external/ ، قم بإجراء التغييرات في المنبع، ثم قم بإبلاغ مشرفي Android بالإصدار الجديد الذي يحتوي على تغييراتك.

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

إحدى الحالات الخاصة المثيرة للاهتمام هي Bionic. معظم التعليمات البرمجية الموجودة موجودة من BSD، لذا ما لم يكن التغيير على تعليمات برمجية جديدة في Bionic، فيرجى إجراء إصلاح أولي، ثم سحب ملف جديد بالكامل من BSD المناسب.

نواة أندرويد

قم بإجراء جميع التغييرات في المنبع. للحصول على إرشادات عامة، اتبع إرشادات مساهمة Android Kernel وصفحة تطوير Kernel Code لـ GKI .

وحدة العناية المركزة

قم بإجراء كافة التغييرات على مشروع ICU في المجلدات external/icu ( icu4c/ و icu4j/ ) على الصفحة الرئيسية لـ ICU-TC . راجع إرسال أخطاء وحدة العناية المركزة وطلبات الميزات للمزيد. أضف التصنيف "android" إلى جميع طلبات Jira الأولية.

كلدر

معظم البيانات اللغوية في وحدة العناية المركزة تأتي من مشروع Unicode CLDR . أرسل جميع الطلبات إلى المنبع وفقًا للمساهمة في CLDR وأضف التصنيف "android".

LLVM/Clang/المترجم-rt

قم بإجراء كافة التغييرات على المشاريع المتعلقة بـ LLVM ( external/clang , external/compiler-rt , external/llvm ) على صفحة البنية التحتية للمترجم LLVM .

mksh

قم بإجراء جميع التغييرات على مشروع MirBSD Korn Shell على external/mksh إما عن طريق إرسال بريد إلكتروني إلى miros-mksh على المجال mirbsd.org (لا يلزم الاشتراك للإرسال هناك) أو على Launchpad .

OpenSSL

قم بإجراء كافة التغييرات على مشروع OpenSSL في external/openssl على صفحة OpenSSL .

V8

قم بإرسال كافة التغييرات إلى مشروع V8 على external/v8 في صفحة إصدار V8 . راجع المساهمة في V8 للحصول على التفاصيل.

WebKit

قم بإجراء جميع التغييرات على مشروع WebKit على external/webkit على صفحة WebKit . ابدأ العملية عن طريق تقديم خطأ WebKit . في الخطأ، استخدم حقول Android للنظام الأساسي ونظام التشغيل فقط إذا كان الخطأ خاصًا بنظام Android. من المرجح أن تحظى الأخطاء باهتمام المراجعين بعد إضافة الإصلاح المقترح وتضمين الاختبارات. راجع المساهمة بالكود في WebKit للحصول على التفاصيل.

زليب

قم بإجراء جميع التغييرات على مشروع zlib على external/zlib على صفحة zlib الرئيسية .