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

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

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

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

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

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

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

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

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

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

إذا كنت من مطوّري Eclipse، يمكنك استخدام تنسيق الرموز الخاصة بالمشروع المحدّد في دليل الإعدادات الذي تتم معالجته تلقائيًا من خلال 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. وقبل المتابعة باتّباع التعليمات الواردة أدناه، يُرجى الاطّلاع على instructions GitHub حول كيفية البدء في استخدام أسلوب HTTPS أو استنساخ بروتوكول النقل الآمن. وإذا كنت تريد معرفة المزيد من المعلومات عن Git بشكلٍ عام، يعدّ Pro Git موردًا جيدًا.

التحقق من الرمز

استخدام HTTPS

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

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

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

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

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 > Android SDK Manager أو شغِّل 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-restrict.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 وأنشأت فرعًا لهذه الميزة الجديدة أو لإصلاح الأخطاء. عند إرسال طلبات مراجعة الرموز من مفترق الطرق الخاص بك، تأكّد من أنّ الشوكة متزامنة مع المستودع الرئيسي. لمزيد من المعلومات، راجع مركز مساعدة 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. انقر على "raw" للحصول على عنوان URL للملف الذي تريد استيراده.
  4. احفظ ملف الاختلاف الأولي في جهازك المحلي باسم مثلissue123456.diff.
  5. انتقِل إلى شجرة عمل Git المحلية وطبّق الفرق باستخدام الأمر patch:
patch -p1 < issue123456.diff

للتحقّق من استيراد الفرق الصحيح، استخدِم السمة git diff في شجرة العمل.

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

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

mvn clean install checkstyle:check

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

بشكل عام، لا يمكن إرسال التعليمة البرمجية إلى مستودع جيت هب حتى يقتنع مراجع التعليمات البرمجية بأن التعليمة البرمجية جاهزة. عند هذه النقطة، يكون الاصطلاح هو الرد بالرسالة "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" في أعلى اليمين، التي تسبق الرقم "Id".

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

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

git checkout -- .