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:
- Tanda tangani Perjanjian Lisensi Kontributor, seperti yang dijelaskan di atas.
- Bergabunglah dengan grup diskusi kami.
- Siapkan lingkungan pengembangan.
- 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.
- Periksa kode, buat masalah baru di codereview.appspot.com, dan selesaikan proses peninjauan kode. Petunjuk terperinci untuk semua proses ini diberikan di bawah.
- 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
- Instal Java 6. Anda mungkin perlu menyetel
JAVA_HOME
variabel. - Instal Maven. (Dokumen ini mengasumsikan Anda telah memiliki pengetahuan dasar tentang perintah Maven.)
- Opsional: Instal Android SDK dan setel 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 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:
- Luncurkan Eclipse dan pilih Window > Android SDK Manager, atau menjalankan
android
pada baris perintah. - 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:
- google-http-java-client
- google-oauth-java-client
- 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:
- Buka masalah dalam codereview.appspot.com.
- Untuk patch yang dimaksud, cari "Download raw" di kanan atas spesifikasi patch.
- Klik "raw" untuk mendapatkan URL file yang akan diimpor.
- Simpan file {i>raw diff<i} ke komputer lokal Anda dengan nama seperti issue123456.diff.
- 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 sebagaiauthor
(--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:
- Pilih masalah di codereview.appspot.com.
- 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 -- .