نحوه همیاری کردن

قراردادهای صدور پروانه همیار (CLA)

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

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

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

نمای کلی ارسال وصله‌ها

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

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

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

  • ما از Git به‌عنوان سیستم کنترل نسخه خود استفاده می‌کنیم.
  • ما از Maven برای سیستم ساخت و همچنین سیستم توزیع دودویی استفاده می‌کنیم.
  • ما از codereview.appspot.com برای بازبینی کد استفاده می‌کنیم. (اما توجه داشته باشید که در ابزار codereview.appspot.com، اصطلاح «مشکل» به‌معنای درخواست بازبینی کد است، درحالی‌که در «ردیاب مشکل GitHub»، «مشکل» به‌معنای درخواست ویژگی یا گزارش اشکال است.)

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

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

پیش‌نیازها

  1. Java 6 را نصب کنید. ممکن است لازم باشد متغیر JAVA_HOME را تنظیم کنید.
  2. Maven را نصب کنید. (این سند فرض می‌کند که شما با فرمان‌های Maven آشنایی اولیه دارید.)
  3. اختیاری: کیت توسعه نرم‌افزار 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 بررسی کنید، باید بااستفاده از HTTP یا SSH در GitHub اصالت‌سنجی شوید. قبل‌از ادامه دادن با دستورالعمل‌های زیر، دستورالعمل‌های GitHub را درباره نحوه شروع کار با شبیه‌سازی HTTPS یا SSH بخوانید. اگر می‌خواهید درباره Git به‌طور کلی بیشتر بدانید، Pro Git منبع خوبی است.

مشغول بررسی کد هستم

استفاده از HTTPS

برای بررسی مخزن کتابخانه در شاخه «اصلی» توسعه، فرمان زیر را اجرا کنید:

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

استفاده از SSH

برای بررسی مخزن کتابخانه در شاخه «اصلی» توسعه، مطمئن شوید که دسترسی نوشتن به مخزن GitHub را دارید، سپس فرمان زیر را اجرا کنید:

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

برای رفتن به شاخه جایگزین، مثلاً ۱.۱۲:

git checkout --track origin/1.12

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

git checkout master

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

git pull

Maven

نصب کردن «خدمات Google Play»

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

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

پس‌از اعمال تغییرات بیشتر، تغییرات جدید را آماده کنید. برای بارگذاری وصله جدید، مثلاً برای شماره مشکل ۱۲۳۴۵۶، فرمان زیر را اجرا کنید: 

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» (خام) کلیک کنید تا نشانی وب فایل را برای وارد کردن دریافت کنید.
  4. فایل diff خام را با نامی مانند issue123456.diff در ماشین محلی‌تان ذخیره کنید.
  5. به درخت کاری Git محلی خود بروید و بااستفاده از فرمان patch، diff را اعمال کنید:
patch -p1 < issue123456.diff

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

درحال آزمایش مجموعه تغییرات

برای اجرای آزمایش‌ها و نصب، از فرمان زیر استفاده کنید:

mvn clean install checkstyle:check

تأیید مجموعه تغییرات در codereview.appspot.com

به‌طور کلی، کد را نمی‌توان به مخزن GitHub ارسال کرد تا زمانی که بازبین کد مطمئن شود که کد آماده است. در این مرحله، طبق روال معمول، با پیام «LGTM» (به‌نظر من خوب است) پاسخ داده می‌شود.

درحال ثبت کد

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

git pull

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

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

git commit

پیامی مانند پیام زیر وارد کنید (با فرض اینکه درحال رفع یا پیاده‌سازی مشکل شماره ۱۲۳ هستید، همان‌طور که در GitHub Issue Tracker فهرست شده است):

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

قبل‌از اولین دونقطه و شرح:

  • اگر این اصلاحیه‌ای برای مشکلی در Issue Tracker است، شماره مشکل را همان‌طور که نشان داده شده است اضافه کنید.
  • اگر این تغییر برای شعبه خاصی است، شماره شعبه را اضافه کنید.
  • شما committer این ثبت خواهید بود، اما لطفاً با علامت‌گذاری نویسنده تغییر به‌عنوان author (--author=<author>)، از او قدردانی کنید.

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

برای روانه کردن تغییر به مخزن GitHub:

git push

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

git pull
git commit
git push

درحال بستن مشکل

حتماً مشکل را در ابزار بازبینی کد ببندید. برای انجام این کار:

  1. مشکل را در codereview.appspot.com انتخاب کنید.
  2. روی «X» که در بالا سمت راست، قبل‌از «شناسه» قرار دارد کلیک کنید.

لغو وصله کردن مجموعه تغییرات

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

git checkout -- .