Cara Berkontribusi

Perjanjian Lisensi Kontributor (CLA)

Sebelum kami dapat menerima patch kode, Anda harus mengirimkan atau Perjanjian Lisensi Kontributor (CLA) perusahaan:

  • Jika Anda adalah individu yang menulis kode sumber asli dan Anda yakin bahwa Anda memiliki kekayaan intelektual, kirimkan CLA perorangan.
  • Jika Anda bekerja di perusahaan, perusahaan Anda harus mengirimkan CLA perusahaan untuk menunjukkan bahwa Anda diizinkan untuk menyumbangkan pekerjaan Anda ke {i>library<i} klien.

Ikuti salah satu dari dua tautan di atas untuk mengakses CLA yang sesuai dan petunjuk cara menandatangani dan mengembalikannya. Setelah kami menerimanya, kami dapat menambahkan Anda pada daftar kontributor resmi.

Ringkasan cara mengirimkan patch

Untuk menyumbangkan 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.
  4. Mengaitkan setiap kumpulan perubahan dengan sebuah Masalah (fitur atau laporan bug permintaan) di Issue Tracker GitHub kami. Buat Masalah baru jika belum ada, dan tugaskan kepada Anda sendiri.
  5. Periksa kode, buat masalah baru di codereview.appspot.com, dan selesaikan proses peninjauan kode. Petunjuk terperinci untuk semua proses ini diberikan di bawah.
  6. Setelah kode Anda ditinjau dan Anda menerima persetujuan, commit kode tersebut. Jika Anda bukan Kontributor resmi, Kontributor akan menarik 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 kode untuk tinjauan sejawat (peer review). (Namun perhatikan bahwa di alat codereview.appspot.com, istilah "issue" berarti permintaan peninjauan kode, sedangkan di Issue Tracker GitHub, merupakan "masalah" adalah permintaan fitur atau laporan bug.)

Jika Anda pengembang Eclipse, gunakan pemformatan kode khusus proyek yang ditentukan di direktori {i> .settings<i} yang otomatis diproses oleh Eclipse.

Menyiapkan lingkungan pengembangan

Prasyarat

  1. Instal Java 6. Anda mungkin perlu menyetel JAVA_HOME variabel.
  2. Instal Maven. (Dokumen ini mengasumsikan Anda telah memiliki pengetahuan dasar tentang perintah Maven.)
  3. Opsional: Instal Android SDK dan setel 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 Anda melanjutkan dengan di bawah ini, baca GitHub petunjuk tentang cara mendapatkan dimulai dengan kloning HTTPS atau SSH. Jika Anda ingin mempelajari lebih lanjut tentang Git di umumnya, Pro Git adalah referensi yang bagus.

Memeriksa kode

Menggunakan HTTPS

Untuk melihat repositori library di "master" pengembangan cabang, jalankan perintah berikut:

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

Menggunakan SSH

Untuk melihat repositori library di "master" pengembangan cabang, maket tentu 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 master:

git checkout master

Untuk mengambil perubahan terbaru dari repositori GitHub dan memperbarui pohon kerja ke commit terbaru:

git pull

Maven

Instal Layanan Google Play

Saat pertama kali menyiapkan proyek, Anda perlu menginstal file google-play-services.jar. Untuk melakukannya:

  1. Luncurkan Eclipse dan pilih Window > Android SDK Manager, atau menjalankan android pada baris perintah.
  2. Scroll ke bagian bawah daftar paket dan pilih Tambahan > Google Play layanan Google.
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 telah dikompilasi ke repositori lokal (misalnya ~/.m2/repository). Mencari biner di 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 Maven Central, Anda harus mengompilasinya dalam urutan berikut:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Mengompilasi dalam urutan ini memastikan bahwa Maven mengambil biner yang telah dikompilasi untuk kompilasi library dependen.

Proses peninjauan kode

Mendownload skrip upload.py

Download skrip upload.py dan jika perlu, tambahkan ke PATH Anda.

Saat pertama kali menjalankan upload.py, Anda akan diminta untuk 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 Anda untuk ditinjau

Sebelum mengirimkan kode untuk ditinjau, Anda harus menjalankan Clirr untuk mengetahui mundur masalah kompatibilitas dalam kode Anda. Jika ada kesalahan yang dilaporkan, Anda harus memperbaikinya atau memperbarui file {i>clirr-ignored-differences.xml).

mvn -q clirr:check

Anda juga harus menjalankan alat FindBugs untuk menangkap bug dalam kode. Jika terjadi error dilaporkan, Anda harus memperbaikinya atau memperbarui findbugs-exclude.xml . (Perhatikan bahwa FindBugs sangat lambat.)

mvn findbugs:check

Setelah perubahan Anda lulus semua pengujian, tambahkan perubahan ke indeks (staging Git area):

git add .

Periksa kembali apakah semua file yang Anda tambahkan, ubah, atau hapus sudah ditampilkan dalam indeks:

git status

Pada output git status, periksa bagian yang disebut "Perubahan yang akan di-commit".

Memulai peninjauan kode

Jika sudah siap 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 Anda membuat lebih banyak perubahan, tahapkan perubahan baru Anda. Untuk mengupload patch baru, misalnya untuk mengeluarkan nomor 123456, jalankan perintah berikut: 

upload.py --rev=HEAD -i 123456

Untuk opsi lainnya, jalankan upload.py --help.

Jika Anda lebih menyukai GitHub alur kerja ini, Anda mungkin telah mengambil cabang repositori GitHub dan membuat cabang untuk fitur baru atau perbaikan bug ini. Jika Anda kirim kode meninjau permintaan dari {i>fork<i} Anda sendiri, pastikan bahwa {i>fork<i} Anda sinkron dengan ke 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 seorang peninjau kode, impor dan uji {i> changeset<i} sebelum Anda menyetujuinya, lalu commit dan mengirim {i> changesets<i} ke repositori jarak jauh.

Mengimpor {i>changeset<i}

Untuk menemukan error lebih awal, pastikan untuk mengambil perubahan terbaru dari remote repositori ke dalam hierarki kerja Anda. Pastikan pohon kerja Anda bersih dan indeks Anda kosong.

Untuk menarik dan menggabungkan commit terbaru dari repositori jarak jauh:

git pull

Untuk memeriksa apa yang ada di hierarki dan indeks Anda yang berfungsi:

git status

Untuk mengimpor patch ke clone Git lokal Anda:

  1. Buka masalah dalam codereview.appspot.com.
  2. Untuk patch yang dimaksud, cari "Download raw" di kanan atas spesifikasi patch.
  3. Klik "raw" untuk mendapatkan URL file yang akan diimpor.
  4. Simpan file {i>raw diff<i} ke komputer lokal Anda dengan nama seperti issue123456.diff.
  5. Buka hierarki kerja Git lokal Anda dan terapkan operasi diff menggunakan patch berikut:
patch -p1 < issue123456.diff

Untuk memeriksa kembali apakah Anda telah mengimpor perbedaan yang benar, lakukan git diff di pohon kerja Anda.

Menguji {i>changeset<i}

Untuk menjalankan pengujian dan menginstal, gunakan perintah berikut:

mvn clean install checkstyle:check

Menyetujui kumpulan perubahan di codereview.appspot.com

Secara umum, kode tidak dapat dikirim ke repositori GitHub hingga peninjau kode puas bahwa kode sudah siap. Pada saat itu, konvensinya adalah untuk membalas dengan pesan "LGTM" (Looks Good To Me).

Mengikat kode

Penting: Sebelum Anda meng-commit kode, tarik perubahan terbaru ke pohon yang berfungsi dan mengupdate hierarki kerja ke commit terbaru dari GitHub repositori:

git pull

Jika ada konflik, selesaikan, lalu pastikan untuk membuat semua pengujian lulus lagi.

Untuk meng-commit kode secara lokal: 

git commit

Masukkan pesan seperti berikut (dengan asumsi Anda sedang memperbaiki atau menerapkan Masalah # 123, seperti yang tercantum di GitHub Issue Tracker):

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

Sebelum tanda titik dua pertama 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 komitmen ini, tetapi harap berikan kredit ke penulis perubahan dengan menandainya sebagai author (--author=<author>).

Setelah deskripsi, selalu sertakan link ke masalah pada peninjauan kode situs Anda. Tautan ini penting karena tanpanya, tidak ada cara mudah untuk mencari tahu tinjauan kode yang terkait dengan commit, yang berguna untuk mempertahankan riwayat diskusi.

Untuk mengirim perubahan ke repositori GitHub:

git push

Jika selama git push Anda menerima pesan error tentang update yang ditolak (mungkin Anda lupa menjalankan git pull), berikut adalah cara menggabungkan dengan perubahan terbaru dan kirim perubahan Anda ke repositori jarak jauh: 

git pull
git commit
git push

Menutup masalah

Pastikan Anda menutup masalah di alat peninjauan kode. Untuk melakukannya:

  1. Pilih masalah di codereview.appspot.com.
  2. Klik tanda "X" yang ada di kiri atas, sebelum "Id".

Melepaskan {i>changeset<i}

Jika karena alasan tertentu Anda memutuskan untuk tidak menjalankan {i>changeset<i} yang diimpor, gunakan perintah berikut untuk menghapusnya. Hati-hati: Tindakan ini benar-benar akan menghapus semua perubahan lokal. 

git checkout -- .