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:
- Yukarıda açıklandığı şekilde bir Katkıda Bulunan Lisans Sözleşmesi imzalayın.
- Tartışma grubumuza katılın.
- Geliştirme ortamınızı ayarlayın.
- 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.
- 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.
- 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
- Java 6'yı yükleyin.
JAVA_HOME
değişkeninizi ayarlamanız gerekebilir. - Maven'i yükleyin. (Bu belgede, Maven komutlarına aşina olduğunuz varsayılmıştır.)
- İsteğe bağlı: Android SDK'yı yükleyin ve ANDROID_HOME değişkeninizi Android için yükleme konumuna ayarlayın.
- 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:
- 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. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Sorunu codereview.appspot.com sayfasında açın.
- Söz konusu yama için yama spesifikasyonunun sağ üst tarafında "Ham indir" ifadesini arayın.
- İçe aktarılacak dosyanın URL'sini almak için "ham"ı tıklayın.
- Ham fark dosyasını sorunu123456.diff gibi bir adla yerel makinenize kaydedin.
- 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ğiauthor
(--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:
- codereview.appspot.com sayfasında sorunu seçin.
- 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 -- .