Cara Berkontribusi

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:

  1. Tanda tangani Perjanjian Lisensi Kontributor, seperti yang dijelaskan di atas.
  2. Bergabunglah dengan grup diskusi kami.
  3. Siapkan lingkungan pengembangan Anda.
  4. 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.
  5. Memeriksa kode, membuat masalah baru di codereview.appspot.com, dan menyelesaikan proses peninjauan kode. Petunjuk terperinci untuk semua proses ini diberikan di bawah.
  6. 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

  1. Instal Java 6. Anda mungkin perlu menetapkan variabel JAVA_HOME.
  2. Instal Maven. (Dokumen ini mengasumsikan Anda telah memiliki pengetahuan dasar tentang perintah Maven.)
  3. Opsional: Instal Android SDK dan tetapkan variabel ANDROID_HOME ke lokasi penginstalan untuk Android.
  4. 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:

  1. Luncurkan Eclipse dan pilih Window > Android SDK Manager, atau jalankan android pada command line.
  2. 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:

  1. google-http-java-client
  2. google-oauth-java-client
  3. 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:

  1. Buka masalah dalam codereview.appspot.com.
  2. Untuk patch yang dimaksud, cari "Download mentah" di kanan atas spesifikasi patch.
  3. Klik "raw" untuk mendapatkan URL untuk file yang akan diimpor.
  4. Simpan file diff mentah ke mesin lokal Anda dengan nama, seperti issue123456.diff.
  5. 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 sebagai author (--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:

  1. Pilih masalah di codereview.appspot.com.
  2. 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 -- .