نحوه مشارکت

قراردادهای مجوز مشارکت کننده (CLA)

قبل از اینکه بتوانیم وصله‌های کد شما را بپذیریم، باید یک قرارداد مجوز مشارکت فردی یا شرکتی (CLA) را ارسال کنید:

  • اگر فردی هستید که کد منبع اصلی را می نویسید و مطمئن هستید که مالکیت معنوی را دارید، یک CLA فردی ارسال کنید.
  • اگر برای یک شرکت کار می کنید، شرکت شما باید یک CLA شرکتی ارائه دهد تا نشان دهد که شما مجاز به مشارکت در کار خود در این کتابخانه مشتری هستید.

برای دسترسی به CLA مناسب و دستورالعمل‌های نحوه امضا و بازگرداندن آن، یکی از دو پیوند بالا را دنبال کنید. پس از دریافت آن، می‌توانیم شما را به فهرست رسمی مشارکت‌کنندگان اضافه کنیم.

مروری بر ارسال پچ ها

برای مشارکت کد در این پروژه، این مراحل کلی را دنبال کنید:

  1. همانطور که در بالا توضیح داده شد، قرارداد مجوز مشارکت را امضا کنید.
  2. به گروه بحث ما بپیوندید.
  3. محیط توسعه خود را تنظیم کنید.
  4. هر یک از تغییرات خود را با یک مشکل (گزارش اشکال یا درخواست ویژگی) در ردیاب مشکلات GitHub ما مرتبط کنید. اگر قبلاً مشکلی وجود ندارد، یک شماره جدید ایجاد کنید و آن را به خودتان اختصاص دهید.
  5. کد را بررسی کنید، یک شماره جدید در codereview.appspot.com ایجاد کنید و فرآیند بررسی کد را تکمیل کنید. دستورالعمل های دقیق برای همه این فرآیندها در زیر آورده شده است.
  6. پس از اینکه کد شما بررسی شد و تاییدیه دریافت کردید، کد را تایید کنید. اگر شما یک Contributor رسمی نیستید، یک Contributor مجموعه تغییرات شما را به مخزن رسمی می کشد.

ما از ابزارها و فرآیندهای زیر استفاده می کنیم:

  • ما از Git به عنوان سیستم کنترل نسخه خود استفاده می کنیم.
  • ما از Maven برای سیستم ساخت و همچنین یک سیستم توزیع باینری استفاده می کنیم.
  • ما از codereview.appspot.com برای بررسی کد استفاده می کنیم. (اما توجه داشته باشید که در ابزار codereview.appspot.com، عبارت "issue" به معنای درخواست بازبینی کد است، در حالی که در GitHub Issue Tracker، "مشکل" یک درخواست ویژگی یا گزارش اشکال است.)

اگر یک برنامه‌نویس Eclipse هستید، از قالب‌بندی کد خاص پروژه مشخص شده در فهرست تنظیمات . که به‌طور خودکار توسط Eclipse پردازش می‌شود، استفاده کنید.

راه اندازی محیط توسعه

پیش نیازها

  1. جاوا 6 را نصب کنید. ممکن است لازم باشد متغیر JAVA_HOME خود را تنظیم کنید.
  2. Maven را نصب کنید. (این سند فرض می کند که شما با دستورات Maven آشنایی اولیه دارید.)
  3. اختیاری: Android SDK را نصب کنید و متغیر ANDROID_HOME خود را روی مکان نصب اندروید تنظیم کنید.
  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

با استفاده از SSH

برای بررسی مخزن کتابخانه در شاخه توسعه "مستر"، مطمئن شوید که دسترسی نوشتن به مخزن GitHub دارید، سپس دستور زیر را اجرا کنید:

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

برای تغییر به یک شاخه جایگزین، به عنوان مثال 1.12:

git checkout --track origin/1.12

برای بازگشت به شاخه اصلی:

git checkout master

برای وارد کردن آخرین تغییرات از مخزن GitHub و به روز رسانی درخت کاری محلی خود به آخرین commit: 

git pull

ماون

سرویس های گوگل پلی را نصب کنید

اولین باری که پروژه را راه اندازی می کنید، باید فایل google-play-services.jar را نصب کنید. برای انجام این کار:

  1. Eclipse را اجرا کنید و Window > Android SDK Manager را انتخاب کنید یا android در خط فرمان اجرا کنید.
  2. به پایین لیست بسته بروید و Extras > Google Play services را انتخاب کنید. 
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-exclude.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 ...

بازبینی کد

اگر یک بازبینی کننده کد هستید، قبل از تأیید تغییرات، آن‌ها را وارد و آزمایش کنید و سپس آن‌ها را متعهد کنید و به مخزن راه دور فشار دهید.

وارد کردن تغییرات

برای تشخیص زودهنگام خطاها، مطمئن شوید که آخرین تغییرات را از مخزن راه دور به درخت کاری خود وارد کنید. مطمئن شوید که درخت کار شما تمیز و شاخص شما خالی است.

برای کشیدن و ادغام آخرین commit ها از مخزن راه دور:

git pull

برای بررسی اینکه چه چیزی در درخت کاری و شاخص شما وجود دارد:

git status

برای وارد کردن یک پچ به کلون Git محلی خود:

  1. مشکل را در codereview.appspot.com باز کنید.
  2. برای پچ مورد نظر، در سمت راست بالای مشخصات وصله، به دنبال «دانلود خام» بگردید.
  3. برای دریافت URL برای وارد کردن فایل، روی "raw" کلیک کنید.
  4. فایل diff خام را با نامی مانند issue123456.diff در دستگاه محلی خود ذخیره کنید.
  5. به درخت کاری Git محلی خود بروید و تفاوت را با استفاده از دستور patch اعمال کنید:
patch -p1 < issue123456.diff

برای بررسی مجدد اینکه تفاوت صحیح را وارد کرده اید، یک git diff در درخت کاری خود انجام دهید.

تست تغییرات

برای اجرای تست ها و نصب از دستور زیر استفاده کنید: 

mvn clean install checkstyle:check

تأیید تغییرات در codereview.appspot.com

به طور کلی، تا زمانی که بازبینی کننده کد از آماده بودن کد راضی نشود، نمی توان کد را به مخزن GitHub فرستاد. در آن مرحله، قرارداد این است که با پیام "LGTM" (برای من خوب به نظر می رسد) پاسخ دهید.

در حال انجام کد

مهم: قبل از اینکه کد خود را commit کنید، آخرین تغییرات را در درخت کاری خود بکشید و درخت کاری خود را به آخرین commit از مخزن GitHub به روز کنید:

git pull

در صورت وجود هر گونه تضاد، آنها را حل کنید، سپس مطمئن شوید که همه آزمون ها را دوباره با موفقیت پشت سر بگذارید.

برای اجرای کد به صورت محلی :

git commit

پیامی مانند زیر را وارد کنید (با فرض اینکه مشکل شماره 123 را برطرف یا اجرا می کنید، همانطور که در ردیاب مشکل GitHub فهرست شده است):

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

قبل از دو نقطه اول و توضیحات:

  • اگر این یک رفع مشکل در ردیاب مشکل است، شماره مشکل را مطابق شکل وارد کنید.
  • اگر این تغییر برای یک شعبه خاص است، شماره شعبه را درج کنید.
  • شما committer این commit خواهید بود، اما لطفاً با علامت گذاری نویسنده تغییر به عنوان author ( --author=<author> ) اعتبار را به او بدهید.

به دنبال توضیحات، همیشه یک پیوند به موضوع را در سایت codereview قرار دهید. این پیوند مهم است زیرا بدون آن، هیچ راه مناسبی برای کشف بررسی کد مرتبط با یک commit وجود ندارد، که برای حفظ تاریخچه بحث مفید است.

برای فشار دادن تغییر به مخزن GitHub:

git push

اگر در حین git push پیام خطایی در مورد رد شدن به‌روزرسانی‌ها دریافت کردید (شاید فراموش کرده باشید git pull اجرا کنید)، در اینجا نحوه ادغام با آخرین تغییرات و فشار دادن تغییرات خود به مخزن از راه دور آورده شده است:

git pull
git commit
git push

بسته شدن موضوع

مطمئن شوید که مشکل را در ابزار بررسی کد ببندید. برای انجام این کار:

  1. مشکل را در codereview.appspot.com انتخاب کنید.
  2. روی "X" که در بالا سمت چپ است، قبل از "Id" کلیک کنید.

حذف وصله مجموعه تغییرات

اگر به دلایلی تصمیم گرفتید که تغییرات وارد شده را انجام ندهید، از دستور زیر برای خلاص شدن از آن استفاده کنید. مراقب باشید : به معنای واقعی کلمه همه تغییرات محلی شما را پاک می کند.

git checkout -- .