Katkıda Bulunma

Katkıda Bulunan Lisans Sözleşmeleri (CLA'lar)

Kod yamalarınızı kabul edebilmemiz için bireysel veya kurumsal bir Katkıda Bulunanlar için Lisans Sözleşmesi (CLA) göndermeniz gerekir:

  • Orijinal kaynak kodu yazan bir şahıssanız ve fikri mülkiyetin size ait olduğundan eminseniz bireysel CLA gönderin.
  • Bir şirket için çalışıyorsanız şirketiniz, çalışmanızı bu istemci kitaplığına ekleme izninizin olduğunu belirtmek için bir kurumsal CLA göndermelidir.

Uygun CLA'ya ve imzalayıp iade etme talimatlarına erişmek için yukarıdaki iki bağlantıdan birini izleyin. E-postanızı aldıktan sonra sizi resmi katkıda bulunanlar listesine ekleyebiliriz.

Yama göndermeye genel bakış

Bu projeye kod eklemek için şu genel adımları uygulayın:

  1. Yukarıda açıklandığı şekilde bir Katkıda Bulunan Lisans Sözleşmesi imzalayın.
  2. Tartışma grubumuza katılın.
  3. Geliştirme ortamınızı ayarlayın.
  4. GitHub Issue Tracker'ımızda değişiklik kümelerinizin her birini bir Sorunla (hata raporu veya özellik isteği) ilişkilendirin. Henüz yoksa yeni bir Sayı oluşturun ve bunu kendinize atayın.
  5. Kodu kontrol edin, codereview.appspot.com adresinde yeni bir sorun oluşturun ve kod inceleme sürecini tamamlayın. Tüm bu süreçlerle ilgili ayrıntılı talimatlar aşağıda verilmiştir.
  6. Kodunuz incelenip onay aldıktan sonra kodu kaydedin. Resmi bir Katkıda Bulunan değilseniz, Katkıda Bulunan bir kullanıcı değişiklik kümenizi resmi depoya çeker.

Aşağıdaki araç ve süreçleri kullanırız:

  • Sürüm kontrol sistemimiz olarak Git'i kullanıyoruz.
  • Derleme sistemi ve ikili dağıtım sistemi için Maven kullanılır.
  • Kod incelemeleri için codereview.appspot.com adresini kullanırız. (Ancak, codereview.appspot.com aracında "sorun" teriminin, kod incelemesi isteği anlamına geldiğini, GitHub Sorun İzleyici'de "sorunun" ise bir özellik isteği veya hata raporu olduğunu unutmayın.)

Eclipse geliştiricisiyseniz .settings dizininde belirtilen ve Eclipse tarafından otomatik olarak işlenen projeye özel kod biçimlendirmesini kullanın.

Geliştirme ortamını ayarlama

Ön koşullar

  1. Java 6'yı yükleyin. JAVA_HOME değişkeninizi ayarlamanız gerekebilir.
  2. Maven'i yükleyin. (Bu belgede, Maven komutlarına aşina olduğunuz varsayılmıştır.)
  3. İsteğe bağlı: Android SDK'yı yükleyin ve ANDROID_HOME değişkeninizi Android için yükleme konumuna ayarlayın.
  4. Git'i yükleyin.

Git ayarlanıyor

Varsayılan görünen adınızı ve e-posta adresinizi ayarlamak için git config komutunu kullanın:

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

Git'ten GitHub ile kimlik doğrulama

GitHub'daki kodu kontrol edebilmek için HTTP veya SSH kullanarak GitHub ile kimliğinizi doğrulamanız gerekir. Aşağıdaki talimatlara devam etmeden önce HTTPS veya SSH klonlamayı kullanmaya başlamayla ilgili GitHub instructions okuyun. Genel olarak Git hakkında daha fazla bilgi edinmek istiyorsanız Pro Git iyi bir kaynaktır.

Kodu kontrol etme

HTTPS'yi kullanma

Geliştirme "ana" dalındaki kitaplık deposuna göz atmak için aşağıdaki komutu çalıştırın:

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

SSH kullanma

Geliştirme "ana" dalındaki kitaplık deposuna göz atmak için GitHub deposuna yazma erişiminiz olduğundan emin olun ve aşağıdaki komutu çalıştırın:

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

Alternatif bir dala (ör. 1.12) geçmek için:

git checkout --track origin/1.12

Ana dala geri dönmek için:

git checkout master

GitHub deposundaki en son değişiklikleri almak ve yerel çalışma ağacınızı en son kaydetme işlemine güncellemek için:

git pull

Maven

Google Play Hizmetleri'ni yükleyin

Projeyi ilk kez oluşturduğunuzda google-play-services.jar dosyasını yüklemeniz gerekir. Bunun için:

  1. Eclipse'i başlatın ve Pencere > Android SDK Yöneticisi'ni seçin veya komut satırında android komutunu çalıştırın.
  2. Paket listesinin alt kısmına gidin ve Ekstralar > Google Play hizmetleri'ni seçin.
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

Projeyi derleme

mvn clean install

Maven, derlenen ikili programları yerel bir depoya yükler (ör. ~/.m2/repository). Maven merkezi deposundan getirmeden önce bu depoda ikili programlar arar.

Not: Bu kitaplık google-http-java-client ve google-oauth-java-client'e bağlıdır. Henüz Maven Central'a yayınlanmamış üç kitaplığın da yeni bir sürümü üzerinde çalışırken, bunları aşağıdaki sırayla derlemeniz gerekir:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Bu sırayla derleme işlemi, Maven'in bağımlı kitaplık derlemesi için derlenen ikili programları almasını sağlar.

Kod inceleme süreci

install.py komut dosyasını indirme

upload.py komut dosyasını indirin ve isteğe bağlı olarak PATH'inize ekleyin.

upload.py uygulamasını ilk kez çalıştırdığınızda sizden uygulamaya özel şifre girmeniz istenir:

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

Kodunuz inceleme için hazırlanıyor

Kodu incelemeye göndermeden önce, kodunuzdaki geriye dönük uyumluluk sorunlarını yakalamak için Clirr'i çalıştırmanız gerekir. Hata bildirilirse bunları düzeltmeniz veya clirr-ignored-differences.xml dosyasını güncellemeniz gerekir.

mvn -q clirr:check

Koddaki hataları yakalamak için FindBugs aracını da çalıştırmanız gerekir. Herhangi bir hata bildirilirse bunları düzeltmeniz veya findbugs-excluded.xml dosyasını güncellemeniz gerekir. (FindBugs'in çok yavaş olduğunu unutmayın.)

mvn findbugs:check

Değişikliğiniz tüm testleri geçtikten sonra değişikliği dizine (Git hazırlık alanı) ekleyin:

git add .

Eklediğiniz, değiştirdiğiniz veya sildiğiniz tüm dosyaların dizine yansıtıldığından emin olun:

git status

git status çıkışında "Uygulanacak değişiklikler" adlı bölümü kontrol edin.

Kod incelemesine başlanıyor

İnceleme için hazır olduğunuzda, codereview.appspot.com adresinde yeni bir sorun oluşturun:

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

Daha fazla değişiklik yaptıktan sonra yeni değişikliklerinizi aşamalandırın. Örneğin 123456 numaralı sorunu içeren yeni bir yama yüklemek için aşağıdaki komutu çalıştırın:

upload.py --rev=HEAD -i 123456

Daha fazla seçenek için upload.py --help komutunu çalıştırın.

Tipik GitHub iş akışını tercih ediyorsanız muhtemelen GitHub deposunu çatallandırmış ve bu yeni özellik ya da hata düzeltmesi için bir dal oluşturmuşsunuzdur. Kendi çatalınızdan kod inceleme istekleri gönderirken çatalınızın yukarı akış deposuyla senkronize olduğundan emin olun. Daha fazla bilgi için çatal senkronizasyonu hakkında GitHub yardımına bakın.

Yükleme.py dosyasını yerel olarak kaydedilen değişiklik kümeleri için de kullanabilirsiniz.

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

Kod inceleme uzmanı

Kod inceleyiciyseniz değişiklik kümelerini onaylamadan önce içe aktarın ve test edin, ardından değişiklik kümelerini kaydedip uzak depoya aktarın.

Değişiklik kümesini içe aktarma

Hataları erken yakalamak için uzak depodaki en son değişiklikleri çalışan ağacınıza çektiğinizden emin olun. Çalışan ağacınızın temiz, dizininizin ise boş olduğundan emin olun.

Uzak depodan en son kaydetme işlemlerini almak ve birleştirmek için:

git pull

Çalışan ağacınızda ve dizininizde neler olduğunu kontrol etmek için:

git status

Bir yamayı yerel Git klonunuza aktarmak için:

  1. Sorunu codereview.appspot.com sayfasında açın.
  2. Söz konusu yama için yama spesifikasyonunun sağ üst tarafında "Ham indir" ifadesini arayın.
  3. İçe aktarılacak dosyanın URL'sini almak için "ham"ı tıklayın.
  4. Ham fark dosyasını sorunu123456.diff gibi bir adla yerel makinenize kaydedin.
  5. Yerel Git çalışma ağacınıza gidin ve patch komutunu kullanarak farkı uygulayın:
patch -p1 < issue123456.diff

Doğru farkı içe aktardığınızdan emin olmak için çalışan ağacınızda bir git diff işlemi yapın.

Değişiklik kümesini test etme

Testleri çalıştırmak ve yüklemek için aşağıdaki komutu kullanın:

mvn clean install checkstyle:check

codereview.appspot.com adresinde bir değişiklik grubunu onaylama

Genel olarak, kod incelemeci kodun hazır olduğundan emin olana kadar kod, GitHub deposuna aktarılamaz. Bu noktada kural, "LGTM" (Bana İyi geliyor) mesajıyla yanıt vermektir.

Kodu kaydetme

Önemli: Kodunuzu kaydetmeden önce, en son değişiklikleri çalışma ağacınıza alın ve çalışma ağacınızı GitHub deposundaki en son kayda güncelleyin:

git pull

Herhangi bir çakışma varsa bunları çözün ve tüm testlerin tekrar geçildiğinden emin olun.

Kodu yerel olarak kaydetmek için:

git commit

Aşağıdaki gibi bir mesaj girin (GitHub Sorun İzleyici'de listelendiği gibi Sorun 123'ü düzelttiğinizi veya uyguladığınızı varsayın):

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

İlk iki nokta üst üste işaretinden ve açıklamadan önce:

  • Bu, Sorun İzleyici'deki bir sorunun çözümüyse gösterilen sorun numarasını belirtin.
  • Belirli bir şube için böyle bir değişiklik söz konusuysa şube numarasını ekleyin.
  • Bu taahhüdün committer adresi siz olacaksınız. Ancak lütfen değişikliği author (--author=<author>) olarak işaretleyerek değişikliği yazan kişiye atıfta bulunun.

Açıklamanın ardından, her zaman kod inceleme sitesine sorunun bağlantısını ekleyin. Bu bağlantı önemlidir, çünkü bağlantı olmadan bir kaydetmeyle ilişkili kod incelemesini anlamanın kolay bir yolu yoktur ve bu da tartışmanın geçmişini korumak için faydalıdır.

Değişikliği GitHub deposuna aktarmak için:

git push

git push sırasında güncellemelerin reddedildiğini bildiren bir hata mesajı alırsanız (git pull çalıştırmayı unutmuş olabilirsiniz) en son değişikliklerle nasıl birleştireceğiniz ve değişikliklerinizi uzak depoya nasıl aktaracağınız aşağıda açıklanmıştır:

git pull
git commit
git push

Sorunu kapatma

Kod inceleme aracında sorunu kapattığınızdan emin olun. Bunun için:

  1. codereview.appspot.com sayfasında sorunu seçin.
  2. Sol üstte, "Kimlik"ten önce gelen "X" işaretini tıklayın.

Değişiklik grubunun yamalarını kaldırma

Herhangi bir nedenle içe aktardığınız bir değişiklik grubunu uygulamamaya karar verirseniz kaldırmak için aşağıdaki komutu kullanın. Dikkatli olun: Bu işlem, tüm yerel değişikliklerinizi tamamen siler.

git checkout -- .