Katkıda Bulunma

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

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

Kod yamalarınızı kabul edebilmemiz için bir şahıs veya kurumsal Katkıda Bulunan 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 tek bir CLA gönderin.
  • Bir şirket için çalışıyorsanız şirketiniz, çalışmanıza bu istemci kitaplığıyla katkıda bulunabileceğinizi belirtmek için şirketin CLA'sını göndermelidir.

Uygun CLA'ya ve imza ve geri ödeme talimatlarına erişmek için yukarıdaki iki bağlantıdan birini izleyin. Bu belgeyi aldıktan sonra sizi resmi katkıda bulunanlar listesine ekleyebiliriz.

Yama göndermeye genel bakış

Bu projeye kodla katkıda bulunmak için aşağıdaki genel adımları uygulayın:

  1. Yukarıda açıklandığı şekilde Katkıda Bulunan Lisans Sözleşmesi'ni imzalayın.
  2. Tartışma grubumuza katılın.
  3. Geliştirme ortamınızı ayarlayın.
  4. Değişiklik gruplarınızın her birini, GitHub Sorun İzleyicimizde bir Sorun (hata raporu veya özellik isteği) ile ilişkilendirin. Henüz yoksa yeni bir Sorun oluşturun ve kendinize atayın.
  5. Koda göz atın, codereview.appspot.com adresinde yeni bir sorun oluşturun ve kod inceleme sürecini tamamlayın. Tüm bu işlemler için ayrıntılı talimatları aşağıda bulabilirsiniz.
  6. Kodunuz incelendikten ve onay aldıktan sonra kodu girin. Resmi Katkıda Bulunan değilseniz resmi katkıda bulunan kullanıcı, değişikliklerinizi resmi depoya çeker.

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

  • Sürüm denetim sistemimiz olarak Git'i kullanıyoruz.
  • Derleme sistemi ve ikili dağıtım sistemi için Maven kullanıyoruz.
  • Kod incelemeleri için codereview.appspot.com kullanılır. (Bununla birlikte, codereview.appspot.com aracındaki "issue" terimi bir kod incelemesi isteği anlamına gelir. GitHub Issue Tracker'da ise bir "sorun", bir özellik isteği veya hata raporudur.)

Eclipse geliştiricisiyseniz Eclipse tarafından otomatik olarak işlenen, .settings dizininde belirtilen 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'ı yükleyin. (Bu dokümanda, Maven komutlarıyla ilgili temel bilgiye sahip 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 ayarlarını yapma

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"

GitHub ile kimlik doğrulama işlemini Git'ten yapma

Kodu GitHub'da kontrol edebilmek için GitHub'da kimliğinizi HTTP veya SSH kullanarak doğrulamanız gerekir. Aşağıdaki talimatlara devam etmeden önce, HTTPS veya SSH klonlamaya nasıl başlayacağınızla ilgili GitHub talimatlarını okuyun. Genel olarak Git hakkında daha fazla bilgi edinmek isterseniz Pro Git iyi bir kaynaktır.

Koda göz atma

HTTPS kullanma

Geliştirme ana modülündeki 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 kullanarak

Geliştirme ana düğümündeki kitaplık deposuna göz atmak için GitHub veri 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 şubeye geçmek için (ör. 1.12):

git checkout --track origin/1.12

Ana dala geri dönmek için:

git checkout master

GitHub veri havuzundaki 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ükleme

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

  1. Eclipse'i başlatın ve Window > Android SDK Manager'ı seçin veya komut satırında android komutunu çalıştırın.
  2. Ekranı kaydırarak paket listesinin alt kısmına gidip Ekstralar ve > 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 veri havuzuna yükler (örneğin, ~/.m2/repository). Maven merkezi veri havuzundan getirmeden önce o depodaki ikili programları arar.

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

  1. google-http-java-istemci
  2. google-oauth-java-istemci
  3. google-api-java-client Bu sırada derleme, Maven'in bağımlı kitaplık derlemesi için derlenmiş 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 bunu PATH yoluna ekleyin.

upload.py öğesini ilk kez çalıştırdığınızda sizden uygulamaya özel bir şifre 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 inceleme için göndermeden önce, kodunuzdaki geriye dönük uyumluluk sorunlarını yakalamak için Clirr'i çalıştırmalısınız. Herhangi bir hata bildirilirse bunları düzeltmeniz veya clirr-ignored-differences.xml dosyasını güncellemeniz gerekir.

mvn -q clirr:check

Koddaki hataları yakalamak için FinderBugs 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ığını bir kez daha kontrol edin:

git status

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

Kod incelemesi başlatılıyor

İncelemeye hazır olduğunuzda codereview.appspot.com'da 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 uygulayın. Yeni bir yama yüklemek için (örneğin, 123456 numaralı sorunu) aşağıdaki komutu çalıştırın: 

upload.py --rev=HEAD -i 123456

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

Tipik bir GitHub iş akışını tercih ediyorsanız büyük olasılıkla GitHub veri deposunu çatallamış ve bu yeni özellik veya hata düzeltmesi için de 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 bir çatalın senkronize edilmesiyle ilgili GitHub yardımını inceleyin.

Ayrıca, yerel olarak taahhüt edilen değişiklik kümeleri için upload.py dosyasını kullanabilirsiniz.

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

Kod incelemeci

Kod inceleyicileri onaylamadan önce içe aktarma ve değiştirme amacıyla değişiklikleri yapın. Ardından, değişiklikleri kaydedin ve uzak depoya aktarın.

Değişiklik kümesi içe aktarılıyor

Hataları erken yakalamak için uzak kod deposundaki en son değişiklikleri çalışma ağacınıza aldığınızdan emin olun. Çalışma ağacınızın temiz olduğundan ve dizininizin boş olduğundan emin olun.

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

git pull

Çalışma ağacınızdaki ve dizininizdeki öğeleri 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ğ üstteki "Ham indir" ifadesini arayın.
  3. İçe aktarılacak dosyanın URL'sini almak için "ham" düğmesini tıklayın.
  4. Ham diff dosyasını, yerel makinenize issue123456.diff gibi bir adla kaydedin.
  5. Yerel Git çalışma ağacınıza gidin ve farkı patch komutunu kullanarak uygulayın:
patch -p1 < issue123456.diff

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

Değişiklik kümesi test ediliyor

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

mvn clean install checkstyle:check

codereview.appspot.com'da değişiklik grubunu onaylama

Genel olarak kod inceleme uzmanı, kodun hazır olduğundan emin olana kadar GitHub veri havuzuna aktarılamaz. Bu noktada gelen mesaj "LGTM" (Bana Uygun Olur) mesajıyla cevaplamaktır.

Kod taahhüt ediliyor

Ö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 veri deposundaki en son kaydetme işlemine güncelleyin:

git pull

Çakışmalar varsa bunları düzeltin. Ardından tüm testleri yeniden geçtiğinizden emin olun.

Kodu yerel olarak uygulamak için: 

git commit

Aşağıdaki gibi bir mesaj girin (GitHub Issue Tracker'da listelenen, 123 numaralı sorunu düzelttiğinizi veya uyguladığınızı varsayıyoruz):

#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 düzeltmesiyse, gösterildiği gibi sorun numarasını ekleyin.
  • Belirli bir dal için bu değişiklik geçerliyse dal numarasını ekleyin.
  • Bu taahhüt size ait committer olacak ancak lütfen author yazarını (--author=<author>) işaretleyerek bu değişikliğin yazarına atıfta bulunun.

Açıklamanın ardından, kod incelemesi sitesine sorunun her zaman bağlantısını ekleyin. Bu bağlantı önemlidir, çünkü bu olmadan, tartışmalarla ilişkili bir geçmişi korumak için yararlı olan bir kaydetme ile ilişkili kod incelemesini anlamanın kolay bir yolu yoktur.

Değişikliği GitHub veri havuzuna aktarmak için:

git push

git push boyunca, reddedilen güncellemelerle ilgili (git pull çalıştırmayı unuttuysanız) bir hata mesajı alırsanız en son değişikliklerle nasıl birleştireceğinizi ve değişikliklerinizi uzak depoya nasıl aktaracağınızı buradan öğrenebilirsiniz: 

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, önceki "Kimlik"ten önce "X"i tıklayın

Değişiklik grubunun yamasını düzeltme

Herhangi bir nedenle içe aktardığınız bir değişiklik kümesini uygulamamaya karar verirseniz bu işlemi kaldırmak için aşağıdaki komutu kullanın. Dikkatli olun: Bölgenizdeki tüm değişiklikler bire bir silinir. 

git checkout -- .