Perjanjian Lisensi Kontributor (CLA)
Sebelum kami dapat menerima patch kode, Anda harus mengirimkan Perjanjian Lisensi Kontributor (CLA) individu atau perusahaan:
- Jika Anda adalah individu yang menulis kode sumber asli dan yakin bahwa Anda memiliki kekayaan intelektual, kirimkan CLA individual.
- Jika Anda bekerja di sebuah perusahaan, perusahaan Anda harus mengirimkan CLA perusahaan untuk menunjukkan bahwa Anda diizinkan untuk memberikan kontribusi karya Anda ke library klien ini.
Ikuti salah satu dari dua link di atas untuk mengakses CLA yang sesuai dan petunjuk tentang cara menandatangani dan mengembalikannya. Setelah menerimanya, kami dapat menambahkan Anda ke daftar kontributor resmi.
Ringkasan cara mengirimkan patch
Untuk memberikan kode ke project ini, ikuti langkah-langkah umum berikut:
- Tanda tangani Perjanjian Lisensi Kontributor, seperti yang dijelaskan di atas.
- Bergabunglah dengan grup diskusi kami.
- Siapkan lingkungan pengembangan Anda.
- Kaitkan setiap set perubahan dengan Masalah (laporan bug atau permintaan fitur) di Issue Tracker GitHub kami. Buat Masalah baru jika belum ada, dan tetapkan masalah tersebut kepada Anda sendiri.
- Memeriksa kode, membuat masalah baru di codereview.appspot.com, dan menyelesaikan proses peninjauan kode. Petunjuk terperinci untuk semua proses ini diberikan di bawah.
- Setelah kode ditinjau dan Anda menerima persetujuan, commit kode tersebut. Jika Anda bukan Kontributor resmi, Kontributor akan mengambil kumpulan perubahan Anda ke repositori resmi.
Kami menggunakan alat dan proses berikut:
- Kami menggunakan Git sebagai sistem kontrol versi.
- Kami menggunakan Maven untuk sistem build, serta sistem distribusi biner.
- Kami menggunakan codereview.appspot.com untuk peninjauan kode. (Namun, perlu diperhatikan bahwa di alat codereview.appspot.com, istilah "masalah" berarti permintaan peninjauan kode, sedangkan di Issue Tracker GitHub, "masalah" adalah permintaan fitur atau laporan bug.)
Jika Anda developer Eclipse, gunakan pemformatan kode khusus project yang ditentukan dalam direktori .settings yang diproses secara otomatis oleh Eclipse.
Menyiapkan lingkungan pengembangan
Prasyarat
- Instal Java 6. Anda mungkin perlu menetapkan variabel
JAVA_HOME
. - Instal Maven. (Dokumen ini mengasumsikan Anda telah memiliki pengetahuan dasar tentang perintah Maven.)
- Opsional: Instal Android SDK dan tetapkan variabel ANDROID_HOME ke lokasi penginstalan untuk Android.
- Instal Git.
Menyiapkan Git
Gunakan perintah git config
untuk menetapkan nama tampilan dan alamat email default:
git config --global user.name "YOUR NAME" git config --global user.email "YOUR EMAIL ADDRESS"
Mengautentikasi dengan GitHub dari Git
Agar dapat memeriksa kode dari GitHub, Anda harus diautentikasi dengan GitHub menggunakan HTTP atau SSH. Sebelum melanjutkan dengan petunjuk di bawah ini, baca instructions GitHub tentang cara memulai cloning HTTPS atau SSH. Jika Anda ingin mempelajari Git secara umum lebih lanjut, Pro Git adalah referensi yang bagus.
Memeriksa kode
Menggunakan HTTPS
Untuk memeriksa repositori library di cabang "master" pengembangan, jalankan perintah berikut:
git clone https://github.com/google/google-api-java-client.git
Menggunakan SSH
Untuk memeriksa repositori library di cabang "master" pengembangan, pastikan Anda memiliki akses tulis ke repositori GitHub, lalu jalankan perintah berikut:
git clone git@github.com:google/google-api-java-client.git
Untuk beralih ke cabang alternatif, misalnya 1.12:
git checkout --track origin/1.12
Untuk beralih kembali ke cabang utama:
git checkout master
Untuk mengambil perubahan terbaru dari repositori GitHub dan mengupdate hierarki pekerjaan lokal ke commit terbaru:
git pull
Maven
Instal Layanan Google Play
Saat pertama kali menyiapkan project, Anda perlu menginstal file google-play-services.jar. Untuk melakukannya:
- Luncurkan Eclipse dan pilih Window > Android SDK Manager, atau jalankan
android
pada command line. - Scroll ke bagian bawah daftar paket dan pilih Tambahan > Layanan 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
Mengompilasi project
mvn clean install
Maven menginstal biner yang dikompilasi ke repositori lokal (misalnya ~/.m2/repository). Library ini menelusuri biner dalam repositori tersebut sebelum mengambil dari repositori pusat Maven.
Catatan: Library ini bergantung pada google-http-java-client dan google-oauth-java-client. Saat mengerjakan versi baru dari ketiga library yang belum dirilis ke pusat Maven, Anda harus mengompilasinya dalam urutan berikut:
- google-http-java-client
- google-oauth-java-client
- google-api-java-client Mengompilasi dengan urutan ini akan memastikan bahwa Maven mengambil biner yang dikompilasi untuk kompilasi library dependen.
Proses peninjauan kode
Mendownload skrip upload.py
Download skrip upload.py dan tambahkan secara opsional ke JALUR Anda.
Saat pertama kali dijalankan, upload.py
akan meminta
sandi khusus aplikasi:
Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com Password for your_email_address@yourdomain.com:
Menyiapkan kode untuk ditinjau
Sebelum mengirim kode untuk ditinjau, Anda harus menjalankan Clirr untuk mengetahui masalah kompatibilitas mundur dalam kode. Jika ada error yang dilaporkan, Anda perlu memperbaikinya atau memperbarui file clirr-ignored-differences.xml.
mvn -q clirr:check
Anda juga harus menjalankan alat FindBugs untuk menangkap bug dalam kode. Jika ada error yang dilaporkan, Anda harus memperbaikinya atau mengupdate file findbugs-exclude.xml. (Perlu diketahui bahwa FindBugs sangat lambat.)
mvn findbugs:check
Setelah perubahan Anda lulus semua pengujian, tambahkan perubahan ke indeks (area staging Git):
git add .
Periksa kembali apakah semua file yang Anda tambahkan, ubah, atau hapus sudah tercermin dalam indeks:
git status
Di output git status
, periksa bagian yang disebut "Perubahan yang akan di-commit".
Memulai peninjauan kode
Jika sudah siap untuk ditinjau, buat masalah baru di codereview.appspot.com:
upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Setelah membuat perubahan lainnya, lakukan tahapan perubahan baru. Untuk mengupload patch baru, misalnya untuk masalah nomor 123456, jalankan perintah berikut:
upload.py --rev=HEAD -i 123456
Untuk opsi lainnya, jalankan upload.py --help
.
Jika lebih menyukai alur kerja GitHub standar, Anda mungkin telah mempergunakan repositori GitHub dan membuat cabang untuk fitur baru atau perbaikan bug ini. Saat Anda mengirim permintaan peninjauan kode dari fork Anda sendiri, pastikan fork Anda disinkronkan dengan repositori upstream. Untuk mengetahui informasi selengkapnya, lihat bantuan GitHub tentang cara menyinkronkan fork.
Anda juga dapat menggunakan upload.py untuk kumpulan perubahan yang di-commit secara lokal.
upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Peninjau kode
Jika Anda adalah peninjau kode, impor dan uji kumpulan perubahan sebelum menyetujuinya, lalu commit dan kirim kumpulan perubahan ke repositori jarak jauh.
Mengimpor changeset
Untuk mendeteksi error lebih awal, pastikan menarik perubahan terbaru dari repositori jarak jauh ke hierarki kerja Anda. Pastikan pohon kerja Anda bersih dan indeks Anda kosong.
Untuk mengambil dan menggabungkan commit terbaru dari repositori jarak jauh:
git pull
Untuk memeriksa apa yang ada di pohon dan indeks kerja Anda:
git status
Untuk mengimpor patch ke clone Git lokal Anda:
- Buka masalah dalam codereview.appspot.com.
- Untuk patch yang dimaksud, cari "Download mentah" di kanan atas spesifikasi patch.
- Klik "raw" untuk mendapatkan URL untuk file yang akan diimpor.
- Simpan file diff mentah ke mesin lokal Anda dengan nama, seperti issue123456.diff.
- Buka pohon kerja Git lokal Anda dan terapkan operasi diff menggunakan perintah
patch
:
patch -p1 < issue123456.diff
Untuk memeriksa kembali apakah Anda telah mengimpor perbedaan yang benar, lakukan git diff
di hierarki kerja Anda.
Menguji changeset
Untuk menjalankan pengujian dan penginstalan, gunakan perintah berikut:
mvn clean install checkstyle:check
Menyetujui changeset di codereview.appspot.com
Secara umum, kode tidak dapat dikirim ke repositori GitHub hingga peninjau kode yakin bahwa kode sudah siap. Pada saat itu, yang perlu dilakukan adalah membalas dengan pesan "LGTM" (Looks Good To Me).
Melakukan commit untuk kode
Penting: Sebelum Anda meng-commit kode, tarik perubahan terbaru ke hierarki yang berfungsi dan update hierarki kerja ke commit terbaru dari repositori GitHub:
git pull
Jika ada konflik, selesaikan konflik tersebut, lalu pastikan semua pengujian diluluskan lagi.
Untuk meng-commit kode secara lokal:
git commit
Masukkan pesan berikut (dengan asumsi Anda memperbaiki atau mengimplementasikan Masalah # 123, seperti yang tercantum di Issue Tracker GitHub):
#123: NullPointerException when passing null to processFoo() http://codereview.appspot.com/123456/
Sebelum tanda titik dua dan deskripsi:
- Jika ini adalah perbaikan untuk masalah di Issue Tracker, sertakan nomor masalah, seperti yang ditunjukkan.
- Jika ini adalah perubahan untuk cabang tertentu, sertakan nomor cabang.
- Anda akan menjadi
committer
dari commit ini, tetapi berikan kredit kepada penulis perubahan dengan menandainya sebagaiauthor
(--author=<author>
).
Setelah deskripsinya, selalu sertakan link ke masalah di situs codereview. Link ini penting karena tanpa link ini, tidak ada cara mudah untuk mengetahui peninjauan kode yang terkait dengan commit, yang berguna untuk mengelola histori diskusi.
Untuk mengirim perubahan ke repositori GitHub:
git push
Jika selama git push
Anda mendapatkan pesan error tentang update yang ditolak (mungkin
Anda lupa menjalankan git pull
), berikut cara menggabungkan dengan perubahan terbaru dan
mengirim perubahan Anda ke repositori jarak jauh:
git pull git commit git push
Menyelesaikan masalah
Pastikan untuk menutup masalah di alat peninjauan kode. Untuk melakukannya:
- Pilih masalah di codereview.appspot.com.
- Klik "X" yang ada di kiri atas, sebelum "ID".
Membatalkan patch changeset
Jika karena alasan tertentu Anda memutuskan untuk tidak meng-commit changeset yang diimpor, gunakan perintah berikut untuk menghapusnya. Hati-hati: Tindakan ini benar-benar menghapus semua perubahan lokal Anda.
git checkout -- .