Bagaimana cara menjadi Patch Guru?¶

Ketika Anda sedang berupaya mengimplementasikan fitur baru atau menambahkan dokumentasi ke yang sudah ada, mudah terbawa oleh karya itu sendiri dan melupakan aturan tidak tertulis dalam menyusun perubahan Anda.

Bagian ini akan memandu Anda melalui cara membuat patch yang ingin ditinjau orang.

Memungkinkan Anda untuk:

Ketahui cara menyusun patch yang membuatnya lebih mudah untuk dipertahankan selama proses peninjauan
Ketahui cara menyusun patch yang lebih mudah bagi anggota komunitas untuk meninjau

Ukuran yang Tepat¶

Meninjau patch besar sangat merepotkan dan makan waktu karena itu kami selalu menyarankan untuk memecah perubahan Anda menjadi blok yang lebih kecil.

Meskipun tidak ada angka ajaib, cobalah untuk keep the size of your changes as small as possible, tetapi di bawah beberapa ratus baris berubah total. Patch yang uji berat dengan sedikit perubahan kode membutuhkan usaha sebanyak perubahan berat kode.

Dalam kesempatan yang jarang terjadi ketika tidak ada gangguan logis yang baik untuk perubahan dan patch Anda dapat tumbuh hingga seribu baris atau lebih. Dalam beberapa kasus itu dapat diterima karena Anda tidak dapat mengekstraksi perubahan tes terkait ke patch lain misalnya, tetapi itu tidak sangat dianjurkan.

Selalu mencoba mengekstrak sebanyak yang Anda bisa ke patch lain, seperti dokumentasi atau bagian logis dari fungsi yang tidak bergantung pada fungsi umum di lapisan bawah.

Patch yang lebih lama membutuhkan lebih banyak waktu untuk meninjau; dimanapun Anda bisa, pertahankan panjang yang wajar. Dan di mana Anda tidak bisa, Anda dapat membantu pengulas dengan menambahkan komentar kode dan menulis pesan komit rinci untuk menggambarkan perubahan yang Anda perkenalkan di patch Anda.

Patch Chains, Depends-On Tag dan Gerrit Topics¶

Dalam kasus kerja implementasi fitur yang kompleks ketika Anda perlu memperkenalkan perubahan pada beberapa modul dari proyek yang sama atau beberapa proyek, Anda harus sangat berhati-hati dalam mengelola dependensi.

Ada beberapa opsi untuk dipilih tergantung pada struktur desain Anda. Anda dapat mengatur perubahan dalam rantai patch atau Anda dapat menggunakan tag 'Depends-On'.

Depends-On Tag¶

Ketika Anda memiliki perubahan dalam beberapa repositori proyek, Anda dapat menandai patch dependen dengan tag 'Depends-On'. Tag akan muncul sebagai tautan dalam pesan komit yang membantu Anda dan juga pengulas untuk melacak dan menavigasi antara dependensi perubahan Anda.

Tag 'Depends-On' adalah penanda pada perubahan Anda dan ketika digunakan patch tidak dapat digabungkan hingga semua dependensinya mendarat (landed).

Tag dapat diterapkan ke tambalan yang diusulkan untuk repositori yang sama juga. Dalam hal ini perubahannya cukup terpisah untuk tetap independen yang berarti bahwa jika Anda perlu memperbaiki perubahan dari komentar ulasan Anda dapat melakukannya berdasarkan setiap patch. Hal ini juga berlaku untuk rebasing setiap patch.

Catatan

Jika Anda menggunakan tag 'Depends-On', Anda perlu mengunduh semua perubahan untuk implementasi fitur atau perubahan dokumentasi untuk menguji fitur atau membuat dokumentasi dengan semua perubahan yang diterapkan. Git tidak akan menangani penanganan dependensi secara otomatis dalam kasus ini.

Rantai patch¶

Dalam beberapa kasus ketika Anda memecah perubahan yang diperlukan untuk blok yang lebih kecil Anda tidak dapat menghindari ketergantungan langsung di antara mereka yang mencegah Anda memiliki perubahan independen. Anda perlu mengatur perubahan Anda dalam rantai untuk mempertahankan dependensi yang memerlukan perhatian tambahan saat Anda bekerja dengan perubahan ini.

Bahkan jika Anda memiliki rantai tambalan Anda masih perlu menyimpan perubahan kode dan tes terkait dalam satu patch karena Anda tidak dapat menjamin bahwa keduanya tiba pada waktunya untuk rilis.

Ketika Anda memiliki rantai, Gerrit membantu Anda dengan mendaftar semua judul komit di kolom 'Related Changes' di sudut kanan atas Gerrit UI. Judul itu juga tautan yang membantu Anda menavigasi di antara perubahan untuk meninjau mereka ketika Anda mengunggah versi baru.

Bagaimana Cara Menangani Rantai (Chains) ?¶

Rantai patch mudah ditangani jika Anda mengingat beberapa rekomendasi:

Selalu memiliki cabang lokal untuk perubahan ini untuk memastikan bahwa Anda tidak mencampurnya bersama dengan perubahan terkait dengan fitur lain atau perbaikan bug.
Selalu tangani rantai sebagai satu blok perubahan dengan mengubah seluruh rantai dan tetap perbarui saat Anda memodifikasi patch untuk memperbaiki komentar ulasan atau menambahkan perubahan ke dalamnya.
Untuk memodifikasi patch dalam rantai Anda perlu menggunakan rebase interaktif:

git rebase -i HEAD^

Anda membutuhkan '^' sebanyak jumlah tambalan yang ingin Anda edit pertama dari atas rantai. Atau Anda mungkin ingin menggunakan git-restack <https://docs.openstack.org/infra/git-restack/> _, yang menunjukkan perintah git rebase yang sesuai untuk Anda.

Gerrit juga menyediakan opsi untuk mengedit patch itu sendiri atau hanya pesan komit dan beberapa lagi untuk perubahan lebih lanjut, seperti memodifikasi pembuat.

Untuk mengunduh rantai penuh, Anda perlu mengunduh patch teratas dan Git akan secara otomatis mengunduh semua patch dependen dalam rantai.
Jika Anda hanya perlu memodifikasi patch teratas dalam rantai yang dapat dilakukan dengan cara yang sama seperti Anda memperbarui patch individu.
Saat Anda mengunggah perubahan dalam rantai, hanya patch yang diperbarui akan diunggah. Ini juga berarti bahwa skor ulasan pada patch yang lebih rendah dalam rantai tidak akan tersentuh.
Selalu periksa perubahan yang Anda buat untuk setiap patch dan berhati-hatilah bahwa Anda menerapkan perubahan di patch yang tepat karena patch masih dapat digabung secara individual dan tidak ada jaminan bahwa seluruh rantai akan mendarat pada waktu yang sama.

Untuk melihat lebih dalam tentang mengelola rantai tambalan, lihat Tutorial: Developing Changes In A Series.

Topik Gerrit¶

Anda memiliki opsi untuk menentukan topik untuk perubahan Anda saat Anda mengunggahnya untuk ditinjau. Sementara topik Gerrit tidak akan menambah ketergantungan pada patch Anda, Anda bisa menerapkan pencarian berdasarkan topik yang akan menunjukkan semua perubahan yang relevan di semua proyek di mana ada patch dengan topik yang sama. Gerrit juga akan menunjukkannya kepada Anda di kolom 'Same Topic' di sudut kanan atas halaman ulasan.

Ini adalah cara yang baik untuk membantu melacak perubahan terkait, biarkan itu menjadi implementasi fitur, perbaikan bug atau pekerjaan dokumentasi.

Bagaimana Menyusun Perubahan Anda?¶

Ketika item pekerjaan Anda tumbuh di atas ukuran tertentu dan Anda perlu mengunggah beberapa patch, sangat penting untuk menyusunnya dengan baik jika terjadi perubahan patch dan perubahan independen.

Ini adalah praktik yang baik untuk mengelompokkan perubahan berdasarkan modul dalam suatu proyek, misalnya perubahan virt driver, manajer komputasi dan perubahan api dalam kasus OpenStack Compute.

Dengan mengelompokkan perubahan per modul, Anda juga dapat membuat rantai atau dependensi berdasarkan hierarki komponen dan selalu mempertahankan perubahan API yang terakhir karena itu akan mengaktifkan fungsionalitas baru dan perubahan itu akan bergantung pada segala hal lain yang perlu Anda sentuh untuk desain Anda.

Selain itu, Anda juga dapat melihat fungsionalitas untuk menemukan blok bangunan yang lebih kecil dan membuat perubahan Anda lebih kecil. Misalnya perubahan pada suatu objek dapat diimplementasikan terlebih dahulu yang akan Anda gunakan nanti ketika Anda menerapkan fungsionalitas API baru.

Structural split of Changes¶

The cardinal rule for creating good commits is to ensure there is only one "logical change" per commit. There are many reasons why this is an important rule:

The smaller the amount of code being changed, the quicker and easier it is to review and identify potential flaws.
If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
When troubleshooting problems using Git's bisect capability, small well defined changes will aid in isolating exactly where the code problem was introduced.
When browsing history using git annotate or git blame, small well defined changes also aid in isolating exactly where and why a piece of code came from.

Konten yang Tepat¶

Perubahan yang tidak terkait dengan implementasi fitur atau laporan bug dapat diunggah tetapi kurang disambut oleh pengulas.

Peningkatan baik kode atau dokumentasi harus menjadi bagian dari upaya yang lebih besar, seperti jika Anda ingin memperbaiki kesalahan ketik dalam dokumentasi maka Anda harus melakukannya untuk blok yang lebih besar, seperti seluruh panduan. Lebih disukai melaporkan berita dengan tugas untuk item pekerjaan seperti ini yang dapat dilacak nanti.

Ini serupa untuk peningkatan kode. Karena komunitasnya besar dan luas di dunia, kami memiliki pedoman pengkodean, tetapi gaya masing-masing individu masih bisa sangat berbeda. Kami tidak menerapkan gaya pengkodean tertentu, oleh karena itu perubahan yang terkait dengan perbaikan yang kurang disambut dan merupakan sumber argumen yang sangat beralasan yang harus dihindari.

Dalam kasus pekerjaan refactoring kode yang membuat kode lebih mudah dibaca dan dipelihara dengan metode restrukturisasi dan menghapus snipet kode yang tidak digunakan, sangat disarankan untuk berkonsultasi dengan tim proyek dan melaporkan sebuah cerita di StoryBoard terlebih dahulu dan kemudian mengunggah perubahan yang relevan ke Gerrit untuk ulasan.

Bagaimana cara menjadi Patch Guru?