كيفية المساهمة

اتفاقيات ترخيص المساهمين (CLA)

قبل أن نتمكن من قبول رموز التصحيح، يجب إرسال إما إرسال أو اتفاقية ترخيص للمساهمين من الشركات (CLA):

  • إذا كنت شخصًا يكتب رمز مصدر أصلي وكنت متأكدًا أنك تملك حقوق الملكية الفكرية، يُرجى إرسال إعلان CLA فردي
  • إذا كنت تعمل لصالح شركة، يجب أن ترسل شركتك اتفاقية ترخيص الشركة. للإشارة إلى أنه مسموح لك بالمساهمة بعملك في مكتبة العملاء هذه.

اتّبِع أيًا من الرابطَين أعلاه للوصول إلى إعلان المقارنة المناسب تعليمات حول كيفية التوقيع وإعادته. يمكننا إضافتك بعد استلامنا الدفعة في القائمة الرسمية للمساهمين

نظرة عامة على إرسال رموز التصحيح

للمساهمة برمز في هذا المشروع، اتبع الخطوات العامة التالية:

  1. وقِّع على "اتفاقية ترخيص المساهمين" كما هو موضَّح أعلاه.
  2. انضم إلى مجموعة المناقشة.
  3. إعداد بيئة التطوير.
  4. ربط كل مجموعة من مجموعات التغييرات بمشكلة (تقرير خطأ أو ميزة GitHub) في أداة تتبُّع المشاكل في GitHub. أنشِئ "عددًا" جديدًا إذا لم يسبق لك ذلك، وخصّصه لنفسك.
  5. تحقَّق من الرمز، وأنشئ مشكلة جديدة على codereview.appspot.com، وأكمِل عملية مراجعة الرمز. في ما يلي التعليمات التفصيلية لجميع هذه العمليات.
  6. بعد مراجعة الرمز والحصول على الموافقة عليه، التزم بالرمز. وإذا لم تكن مساهمًا رسميًا، يسحب المساهم مجموعة تغييراتك إلى المستودع الرسمي.

نستخدم الأدوات والعمليات التالية:

  • نستخدم Git كنظام للتحكم في الإصدارات.
  • ونستخدم Maven مع نظام التصميم وكذلك نظام توزيع ثنائي.
  • نستخدم codereview.appspot.com للترميز. الزملاء. (ولكن تجدر الإشارة إلى أنّه في أداة codereview.appspot.com، إنّ المصطلح "issue" تعني طلب مراجعة رمز، بينما تظهر كلمة "مشكلة" في أداة تتبُّع المشاكل في GitHub هو طلب ميزة أو تقرير خطأ).

إذا كنت مطوّر برامج Eclipse، يمكنك استخدام تنسيق الرمز الخاص بالمشروع. المحدد في دليل .settings الذي تتم معالجته تلقائيًا بواسطة Eclipse.

إعداد بيئة التطوير

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

  1. ثبِّت Java 6. قد تحتاج إلى ضبط JAVA_HOME المتغير.
  2. ثبِّت Maven. (يعرض هذا المستند أن لديك معرفة أساسية بأوامر Maven).
  3. اختياري: تثبيت حزمة تطوير البرامج (SDK) لنظام التشغيل Android واضبط متغيّر ANDROID_Home على موقع التثبيت في نظام Android.
  4. ثبِّت Git.

إعداد Git

استخدِم الأمر git config لضبط الاسم المعروض وعنوان البريد الإلكتروني التلقائيَين:

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

المصادقة مع GitHub من Git

للاطلاع على الرمز من GitHub، يجب المصادقة على GitHub باستخدام HTTP أو SSH. قبل مواصلة استخدام التعليمات أدناه، يُرجى قراءة GitHub التعليمات حول كيفية الحصول على باستنساخ HTTPS أو SSH. إذا كنت تريد معرفة المزيد عن Git في بشكل عام، تُعدّ Pro Git موردًا جيدًا.

التحقق من التعليمة البرمجية

استخدام HTTPS

للتحقق من مستودع المكتبة في تطوير "master" غصن قم بتشغيل الأمر التالي:

git clone https://github.com/google/google-api-java-client.git

استخدام بروتوكول النقل الآمن

للتحقق من مستودع المكتبة في تطوير "master" فرع، صنع بالتأكيد حق الوصول للكتابة إلى مستودع جيت هب، فشغِّل الأمر التالي:

git clone git@github.com:google/google-api-java-client.git

للتبديل إلى فرع بديل، على سبيل المثال 1.12:

git checkout --track origin/1.12

للرجوع إلى الفرع الرئيسي:

git checkout master

للاطّلاع على آخر التغييرات من مستودع جيت هب وتحديث شجرة العمل على أحدث الالتزامات:

git pull

Maven

تثبيت "خدمات Google Play"

في المرة الأولى التي تقوم فيها بإعداد المشروع، تحتاج إلى تثبيت google-play-services.jar. ولإجراء ذلك:

  1. ابدأ تشغيل Eclipse واختَر Window > (نافذة >) تطبيق "إدارة حزمة تطوير البرامج (SDK) لنظام التشغيل Android"، أو تشغيل android على سطر الأوامر.
  2. قم بالتمرير إلى أسفل قائمة الحزم وحدد إضافية > Google Play .
mvn install:install-file \
           -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \
           -DgroupId=com.google.android.google-play-services \
           -DartifactId=google-play-services \
           -Dversion=1 \
           -Dpackaging=jar

تجميع المشروع

mvn clean install

تثبّت Maven برامج ثنائية تم تجميعها في مستودع محلي (على سبيل المثال: ~/.m2/repository). وهي تبحث عن البرامج الثنائية في هذا المستودع قبل استرجاعها من مستودع Maven المركزي.

ملاحظة: تعتمد هذه المكتبة على google-http-java-client وgoogle-oauth-java-client. عند العمل على إصدار جديد من المكتبات الثلاث التي لم يتمّ إصدارها إلى الآن إلى Maven Central، يجب تجميعها بالترتيب التالي:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client يضمن التجميع بهذا الترتيب أن تختار Maven البرامج الثنائية التي تم تجميعها تجميع المكتبة التابعة.

عملية مراجعة الرمز

تنزيل النص البرمجي upload.py

تنزيل النص البرمجي upload.py ويمكنك اختياريًا إضافته إلى PATH.

عند تشغيل "upload.py" للمرة الأولى، سيُطلب منك إدخال كلمة المرور الخاصة بالتطبيقات:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

جارٍ تحضير الرمز للمراجعة

قبل إرسال الرمز للمراجعة، يجب تشغيل Clirr للرجوع إلى الخلف. مشكلات التوافق في التعليمات البرمجية الخاصة بك. إذا تم الإبلاغ عن أي أخطاء، عليك إصلاحها أو تحديث ملف clirr-ignored-differences.xml.

mvn -q clirr:check

يجب أيضًا تشغيل أداة FindBugs لرصد الأخطاء في الرمز البرمجي. في حال حدوث أي أخطاء التي يتم الإبلاغ عنها، فستحتاج إما إلى إصلاحها أو تحديث ملف findbugs-exclusion.xml. الملف. (يُرجى العِلم أنّ تطبيق FindBugs بطيء جدًا).

mvn findbugs:check

بعد أن يجتاز التغيير جميع الاختبارات، أضِف التغيير إلى الفهرس (تقسيم Git المنطقة):

git add .

التحقّق من أنّ جميع الملفات التي أضفتها أو عدّلتها أو حذفتها تظهر في الفهرس:

git status

في ناتج git status، راجِع القسم بعنوان "التغييرات المطلوب الالتزام بها".

بدء مراجعة الرمز

عندما تكون جاهزًا للمراجعة، أنشئ مشكلة جديدة على codereview.appspot.com: 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

بعد إجراء المزيد من التغييرات، نظِّم تغييراتك الجديدة. لتحميل رمز تصحيح جديد، يُرجى اتّباع الخطوات التالية: على سبيل المثال، لإصدار رقم 123456، شغِّل الأمر التالي: 

upload.py --rev=HEAD -i 123456

لمزيد من الخيارات، يمكنك تشغيل "upload.py --help".

إذا كنت تفضل GitHub النموذجي أو سير العمل من المحتمل أنك قمت مستودع جيت هب وإنشاء فرع لهذه الميزة الجديدة أو إصلاح الأخطاء. عندما تريد إرسال الرمز ومراجعة الطلبات من شوكتك الخاصة، فتأكد من أن شوكتك متزامنة مع المستودع الرئيسي. لمزيد من المعلومات، يُرجى الاطّلاع على مركز مساعدة GitHub حول كيفية مزامنة شوكة

يمكنك أيضًا استخدام ملف upload.py لمجموعات التغييرات المحلية أيضًا.

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

مُراجع الرموز

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

استيراد مجموعة تغييرات

لرصد الأخطاء مبكرًا، احرص على سحب آخر التغييرات من جهاز التحكّم عن بُعد. مستودع في شجرة العمل لديك. تأكد من أن شجرة عملك نظيفة الفهرس فارغ.

للحصول على أحدث عمليّات الشراء ودمجها من المستودع البعيد:

git pull

للتحقق مما يتضمنه شجرة العمل والفهرس:

git status

لاستيراد رمز تصحيح إلى نسخة Git طبق الأصل، اتّبِع الخطوات التالية:

  1. افتح المشكلة داخل codereview.appspot.com.
  2. للبحث عن رمز التصحيح المعنيّ، ابحث عن "تنزيل الملف الأولي". في أعلى يمين مواصفات التصحيح.
  3. انقر على "خام" للحصول على عنوان URL للملف المطلوب استيراده.
  4. احفظ ملف الاختلاف الأولي على جهازك المحلي باستخدام اسم مثل المشكلة123456.diff.
  5. انتقِل إلى شجرة عمل Git المحلية وطبّق الفرق باستخدام patch :
patch -p1 < issue123456.diff

للتأكّد من استيراد الاختلافات الصحيحة، يمكنك إجراء git diff في شجرة عملك.

اختبار مجموعة التغييرات

لإجراء الاختبارات والتثبيت، استخدِم الأمر التالي:

mvn clean install checkstyle:check

الموافقة على مجموعة تغييرات على codereview.appspot.com

بشكل عام، لا يمكن إرسال الرموز البرمجية إلى مستودع GitHub حتى يراجع مُراجع الرموز راضيًا عن أن الرمز جاهز. في هذه المرحلة، الاصطلاح هو الرد مع الرسالة "LGTM" (يبدو جيدًا بالنسبة إليّ).

تنفيذ الرمز

ملاحظة مهمة: قبل تطبيق الرمز، اسحب آخر التغييرات إلى شجرة العمل وتحديث شجرة العمل إلى آخر الالتزامات من GitHub المستودع:

git pull

إذا كان هناك أي تعارضات، فعليك حلها، ثم التأكد من إجراء جميع الاختبارات المرور مرة أخرى.

التزام الرمز محليًا: 

git commit

أدخل رسالة مثل ما يلي (بافتراض أنك تعمل على إصلاح أو تنفيذ العدد رقم 123، كما هو وارد في GitHub أداة تتبُّع المشاكل:

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

قبل النقطتين الأولى والوصف:

  • إذا كان هذا قد تم إصلاح مشكلة في أداة تتبُّع المشاكل، اذكر رقم المشكلة كما هو موضَّح.
  • إذا كان هذا تغييرًا لفرع معين، فقم بتضمين رقم الفرع.
  • ستكون أنت الشخص committer في هذا الالتزام، ولكن يُرجى ذِكر اسم مؤلف التغيير من خلال وضع علامة عليه باعتباره author (--author=<author>).

باتباع الوصف، قم دائمًا بتضمين رابط للمشكلة في مراجعة التعليمات البرمجية موقعك. هذا الرابط مهم لأنه بدونه، لا توجد طريقة ملائمة اكتشاف مراجعة التعليمة البرمجية المرتبطة بالالتزام، وهو أمر مفيد الحفاظ على تاريخ المناقشة.

لدفع التغيير إلى مستودع جيت هب:

git push

في حال ظهور رسالة خطأ خلال git push بشأن رفض التحديثات (ربما نسيت تشغيل git pull)، إليك كيفية الدمج مع آخر التغييرات إرسال التغييرات إلى المستودع البعيد: 

git pull
git commit
git push

إغلاق المشكلة

احرص على إغلاق المشكلة في أداة مراجعة الرمز. ولإجراء ذلك:

  1. اختَر المشكلة في codereview.appspot.com.
  2. انقر على "X". الموجود في أعلى اليسار، قبل "المعرف".

إلغاء تصحيح مجموعة تغييرات

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

git checkout -- .