योगदान करने का तरीका

योगदान देने वाले के लिए लाइसेंस देने के लिए कानूनी समझौते (सीएलए)

इससे पहले कि हम आपके कोड पैच को स्वीकार करें, आपको व्यक्तिगत रूप से या कॉर्पोरेट कॉन्ट्रिब्यूटर लाइसेंस एग्रीमेंट (सीएलए) सबमिट करना होगा:

  • अगर आप ओरिजनल सोर्स कोड लिखने वाले एक व्यक्ति हैं और आपको पक्के तौर पर पता है कि बौद्धिक संपत्ति के मालिक आप ही हैं, तो एक व्यक्तिगत सीएलए सबमिट करें.
  • अगर आप किसी कंपनी के लिए काम करते हैं, तो आपकी कंपनी को एक कॉर्पोरेट सीएलए सबमिट करना होगा, ताकि यह बताया जा सके कि आपके पास इस क्लाइंट लाइब्रेरी में अपने काम का योगदान देने की अनुमति है.

सही सीएलए को ऐक्सेस करने के लिए, ऊपर दिए गए दो लिंक में से किसी एक का पालन करें. साथ ही, हस्ताक्षर करने और उसे लौटाने के तरीके के बारे में निर्देश देखें. योगदान मिल जाने के बाद, हम आपको योगदान देने वालों की आधिकारिक सूची में जोड़ सकते हैं.

पैच सबमिट करने के बारे में खास जानकारी

इस प्रोजेक्ट में कोड का योगदान देने के लिए, यह सामान्य तरीका अपनाएं:

  1. ऊपर बताए गए तरीके से, योगदान देने वाले के लाइसेंस के समझौते पर हस्ताक्षर करें.
  2. हमारे चर्चा समूह में शामिल हों.
  3. अपना डेवलपमेंट एनवायरमेंट सेट अप करें.
  4. अपने हर बदलावसेट को हमारे GitHub समस्या ट्रैकर में किसी समस्या (गड़बड़ी की रिपोर्ट या सुविधा का अनुरोध) से जोड़ें. अगर पहले से कोई समस्या मौजूद नहीं है, तो एक नई समस्या बनाएं और उसे खुद को असाइन करें.
  5. कोड देखें, codereview.appspot.com पर नई समस्या बनाएं, और कोड की समीक्षा की प्रक्रिया पूरी करें. इन सभी प्रोसेस के बारे में ज़्यादा जानकारी के लिए निर्देश नीचे दिए गए हैं.
  6. आपके कोड की समीक्षा होने और अनुमति मिल जाने के बाद, कोड जनरेट करें. अगर आप आधिकारिक योगदान देने वाले व्यक्ति नहीं हैं, तो योगदान देने वाला व्यक्ति आपके बदलाव को आधिकारिक डेटा स्टोर करने की जगह में ले जाता है.

हम नीचे दिए गए टूल और प्रोसेस का इस्तेमाल करते हैं:

  • हम अपने वर्शन कंट्रोल सिस्टम के तौर पर Git का इस्तेमाल करते हैं.
  • हम बिल्ड सिस्टम और बाइनरी डिस्ट्रिब्यूशन सिस्टम के लिए, Maven का इस्तेमाल करते हैं.
  • हम कोड की समीक्षाओं के लिए codereview.appspot.com का इस्तेमाल करते हैं. (ध्यान दें कि codereview.appspot.com टूल में "समस्या" शब्द का मतलब कोड की समीक्षा का अनुरोध है. वहीं, GitHub Issue Tracker में, "समस्या" एक सुविधा का अनुरोध या गड़बड़ी की रिपोर्ट है.)

अगर आप Eclipse डेवलपर हैं, तो .settings डायरेक्ट्री में बताए गए प्रोजेक्ट के हिसाब से कोड फ़ॉर्मैटिंग का इस्तेमाल करें, जिसे Eclipse अपने-आप प्रोसेस करता है.

डेवलपमेंट एनवायरमेंट सेट अप करना

ज़रूरी शर्तें

  1. Java 6 इंस्टॉल करें. आपको अपना JAVA_HOME वैरिएबल सेट करना पड़ सकता है.
  2. Maven इंस्टॉल करें. (इस दस्तावेज़ में यह माना गया है कि आपको Maven कमांड के बारे में बुनियादी जानकारी है.)
  3. ज़रूरी नहीं: Android SDK टूल इंस्टॉल करें और ANDROID_HOME में, Android डिवाइस को इंस्टॉल करने की जगह पर सेट करें.
  4. Git इंस्टॉल करें.

Git सेट अप करना

अपना डिफ़ॉल्ट डिसप्ले नेम और ईमेल पता सेट करने के लिए, git config कमांड का इस्तेमाल करें:

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

Git से GitHub के साथ पुष्टि करना

GitHub से कोड देखने के लिए, आपको एचटीटीपी या एसएसएच का इस्तेमाल करके, GitHub की पुष्टि करनी होगी. नीचे दिए गए निर्देशों की मदद से आगे बढ़ने से पहले, एचटीटीपीएस या एसएसएच की नकल करने का तरीका जानने के लिए, GitHub के instructions पढ़ें. अगर आपको Git के बारे में ज़्यादा जानना है, तो Pro Git एक अच्छा संसाधन है.

कोड की जांच की जा रही है

एचटीटीपीएस का इस्तेमाल करना

डेवलपमेंट "मास्टर" ब्रांच में लाइब्रेरी रिपॉज़िटरी देखने के लिए, नीचे दिए गए कमांड चलाएं:

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

एसएसएच का इस्तेमाल करना

डेवलपमेंट "मास्टर" ब्रांच में लाइब्रेरी रिपॉज़िटरी देखने के लिए, पक्का करें कि आपके पास GitHub रिपॉज़िटरी में लिखने का ऐक्सेस है. इसके बाद, यह कमांड चलाएं:

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

किसी दूसरी ब्रांच पर स्विच करने के लिए, उदाहरण के लिए 1.12:

git checkout --track origin/1.12

मास्टर ब्रांच पर वापस जाने के लिए:

git checkout master

GitHub रिपॉज़िटरी से नए बदलाव देखने और अपने लोकल वर्किंग ट्री को सबसे नए वर्शन में अपडेट करने के लिए:

git pull

Maven

Google Play services ऐप्लिकेशन को इंस्टॉल करें

पहली बार प्रोजेक्ट सेट अप करते समय, आपको google-play-services.jar फ़ाइल इंस्टॉल करनी होगी. ऐसा करने के लिए:

  1. Eclipse लॉन्च करें और विंडो > Android SDK मैनेजर चुनें या कमांड लाइन पर 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-excluded.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. इंपोर्ट की जाने वाली फ़ाइल का यूआरएल पाने के लिए, "रॉ" पर क्लिक करें.
  4. रॉ डिफ़ फ़ाइल को अपने लोकल मशीन में, issue123456.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>) के रूप में मार्क करके उसका श्रेय दें.

जानकारी के बाद, Codereview साइट पर समस्या से जुड़ा लिंक हमेशा शामिल करें. यह लिंक अहम है, क्योंकि इसके बिना, किसी तय शर्त से जुड़ी कोड की समीक्षा को समझने का कोई आसान तरीका नहीं है. इससे चर्चा के इतिहास को बनाए रखने में मदद मिलती है.

GitHub रिपॉज़िटरी में बदलाव करने के लिए:

git push

अगर git push के दौरान आपको अपडेट अस्वीकार होने के बारे में गड़बड़ी का कोई मैसेज मिलता है (शायद आप git pull चलाना भूल गए हैं), तो नए बदलावों के साथ मर्ज करने और अपने बदलावों को रिमोट रिपॉज़िटरी में पुश करने का तरीका यहां बताया गया है: 

git pull
git commit
git push

इस समस्या को हल करना

पक्का करें कि कोड-समीक्षा टूल में जाकर, समस्या को बंद कर दिया गया हो. ऐसा करने के लिए:

  1. codereview.appspot.com में जाकर समस्या चुनें.
  2. सबसे ऊपर बाईं ओर मौजूद, "Id" से पहले "X" पर क्लिक करें.

बदलावों के सेट को अनपैच करना

अगर किसी वजह से आपने इंपोर्ट किए गए किसी बदलाव को लागू न करने का फ़ैसला लिया है, तो उसे हटाने के लिए नीचे दिए गए निर्देश का इस्तेमाल करें. सावधान रहें: यह आपके सभी स्थानीय बदलावों को मिटा देता है. 

git checkout -- .