Kekacauan akrab dalam nama-nama komitmen. Gambar yang akrab?Tentunya Anda tahu
git-flow . Ini adalah seperangkat konvensi percabangan yang hebat di Git. Ini didokumentasikan dengan baik dan didistribusikan secara luas. Biasanya kita terbiasa dengan percabangan yang benar dan berbicara banyak tentang hal itu, tetapi, sayangnya, kita terlalu sedikit memperhatikan masalah penamaan komit, itulah sebabnya pesan dalam Git sering ditulis secara tidak sistematis.
Nama saya Yerzhan Tashbenbetov, saya bekerja di salah satu tim Yandex.Market. Dan hari ini saya akan memberi tahu pembaca Habr alat apa yang kami gunakan untuk membuat komitmen yang berarti dalam tim. Saya mengundang Anda untuk bergabung dalam diskusi tentang topik ini.
Kurangnya kesepakatan tentang penamaan melakukan membuatnya sulit untuk bekerja dengan sejarah di Git. Ini ada di tim kami. Sebelum menggunakan aturan umum untuk semua dan menerapkan otomasi, tipikal komitmen adalah sebagai berikut:
SECRETMRKT-700: , . SECRETMRKT-701, SECRETMRKT-702: ...
Pertama, setiap pengembang menulis pesan sesuai keinginannya: seseorang menggambarkan tugas, seseorang mendaftar perubahan yang dibuat, seseorang menggunakan generator frasa acak. Semuanya bertentangan. Kedua, nomor tugas yang ada dalam komit sering kali disingkat menjadi teks bermanfaat. Semua ini membuatnya sulit untuk bekerja secara efektif dengan sejarah di Git.
Untuk alasan ini, kami menerapkan standar
Komitmen Konvensional dalam tim, mulai membuat komitmen di komit utilitas konsol dan memeriksa hasilnya menggunakan
commitlint . Akibatnya, komit telah berubah dan terlihat seperti ini:
refactor(tutorial): feat(products): fix(products):
Membaca cerita dan mengenali perubahan menjadi lebih mudah. Kami tidak menolak untuk menentukan nomor tugas, semuanya dengan rapi dipindahkan ke dalam komitmen sesuai dengan
konvensi Komitmen Konvensional .
Selanjutnya, saya akan menunjukkan kepada Anda bagaimana mencapai urutan serupa di Git.
Praktik terbaik, rekomendasi, dan solusi umum untuk penamaan berkomitmen
Jika Anda mencoba memahami praktik apa yang digunakan dalam industri ini, Anda dapat menemukan opsi berikut:
- Artikel dengan tips umum untuk menulis berkomitmen. Sebagian besar, mereka cukup logis dan membuka topik yang bagus, tetapi ada perasaan tidak teratur dan kurangnya solusi komprehensif untuk masalah ini.
- Standar untuk penulisan berkomitmen. Ada beberapa dari mereka. Mereka adalah dokumen dengan daftar aturan yang jelas, cukup sering ditulis khusus untuk perpustakaan atau kerangka kerja yang besar. Standar-standar ini mengesankan dengan pendekatan sistematis, popularitas, dan dukungan dalam komunitas open-source.
Kami membutuhkan lebih banyak pesanan dalam melakukan!
Metodologi Komitmen Konvensional menonjol dari standar lain dan layak untuk dicermati karena sejumlah alasan:
- Ini didokumentasikan dan dirancang dengan baik. Spesifikasinya memberikan jawaban atas pertanyaan paling umum.
- Pembuat konvensi ini terinspirasi oleh persyaratan untuk menulis, yang digunakan dalam kerangka kerja AngularJS yang populer dan telah teruji waktu.
- Aturan konvensi diikuti oleh beberapa perpustakaan open-source yang besar dan populer (seperti yargs dan lerna ).
- Untuk plus, saya akan mengambil persiapan untuk pembentukan otomatis Catatan Rilis dan Ubah Log.
Contoh dari komitmen terhadap standar ini: fix(products): - . : SECRETMRKT-578, SECRETMRKT-602
Poin-poin penting dari Komitmen Konvensional
- Pengembang harus mematuhi struktur komit berikut:
<type> (<scope>): <subject>
<body>
<footer>
- Komit harus memiliki tajuk, mungkin badan dan catatan kaki.
- Header komit harus dimulai dengan jenis yang menunjukkan spesifikasi perubahan yang dibuat pada basis kode, dan diakhiri dengan deskripsi.
- Seiring dengan prestasi wajib, perbaikan (penggunaan yang diatur secara ketat), jenis lainnya diperbolehkan.
- Komit dapat memiliki cakupan . Ini mencirikan sepotong kode yang telah dipengaruhi oleh perubahan. Area mengikuti tipe komit. Standar tidak mengatur daftar area yang jelas. Contoh area: eslint, git, analytics, dll.
- Deskripsi komit harus segera setelah jenis / area.
- Badan komit dapat digunakan untuk menelusuri perubahan. Badan harus dipisahkan dari uraian dengan garis kosong.
- Footer harus digunakan untuk menentukan tautan eksternal, konteks komit, atau informasi meta lainnya. Footer harus dipisahkan dari tubuh dengan garis kosong.
Selain aturan yang tercantum dalam konvensi, kami menggunakan rekomendasi populer berikut:
- Dalam tubuh komit kami menulis apa yang telah diubah dan mengapa .
- Kami menggunakan jenis komitmen berikut:
| membangun | Bangun proyek atau ubah dependensi eksternal |
| ci | Konfigurasi dan skrip CI |
| docs | Pembaruan Dokumentasi |
| feat | Menambahkan fungsi baru |
| memperbaiki | Perbaikan bug |
| perf | Perubahan Peningkatan Kinerja |
| refactor | Mengedit kode tanpa memperbaiki bug atau menambahkan fitur baru |
| Kembalikan | Kembalikan ke komitmen sebelumnya |
| gaya | Pengeditan gaya kode (tab, indentasi, titik, koma, dll.) |
| tes | Menambahkan Tes |
- Kami menulis deskripsi dalam mood imperatif , seperti halnya Git sendiri.
Gabung cabang 'fix / SECRETMRKT-749-fix-typos-in-title'
- Jangan unggah deskripsi komit dengan tanda baca.
Standar Komitmen konvensional yang digunakan oleh kontributor lerna
Bagaimana cara beralih ke nama commit yang benar?
Perlu menambahkan otomatisasi dan kenyamanan. Untuk mengatasi masalah ini, kita memerlukan dua alat: komit generator dan serasah komit, dikonfigurasi untuk memeriksa sebelum mendorong ke repositori.
Siapkan utilitas komit
Alat ini memungkinkan Anda untuk menghasilkan komit menggunakan panduan bawaan. Selain itu, komitmen juga didukung oleh komunitas dan, berkat modul tambahan, sangat dapat disesuaikan.
- Instal utilitas commitizen secara global (Anda mungkin memerlukan hak administrator).
npm i -g commitizen
- Selanjutnya, instal adaptor yang dapat disesuaikan cz . Diperlukan untuk mengonfigurasi templat dengan pertanyaan yang digunakan oleh utilitas commitizen .
npm i -D cz-customizable
- Mari kita membuat file commitizen.js, perlu mengkonfigurasi cz-customizable. Tempatkan file yang dibuat di direktori ./config/git. Saya sarankan untuk tidak membuang proyek root dengan file konfigurasi dan mencoba untuk mengelompokkan file dalam folder yang disiapkan untuk ini. Konten:
Tampilkan commitizen.js "use strict"; module.exports = {
- Tambahkan tautan ke cz-customizable dan file konfigurasi yang sebelumnya dibuat di package.json:
Perlihatkan bagian dari package.json { "config": { "commitizen": { "path": "node_modules/cz-customizable" }, "cz-customizable": { "config": "config/git/commitizen.js" } }, }
- Mari kita periksa hasilnya. Ketikkan perintah berikut di terminal:
git cz
Wisaya komitmen pertama-tama akan mengumpulkan informasi tentang jenis, area komit, kemudian secara berurutan meminta teks yang akan ada dalam deskripsi, di tubuh, di footer dan, setelah persetujuan Anda, akan membuat komit.
Pastikan untuk melihat contoh utilitas komitnat yang dikonfigurasi dan adaptor cz-cusomizable yang terhubung dengannya
Siapkan utilitas husky dan commit
- Instal husky dan komitmen dalam proyek:
npm i -D husky @commitlint/cli
- Dengan husky, kami akan menambahkan cek komit. Untuk melakukan ini, di package.json, segera setelah skrip, tambahkan kait berikut dan tunjukkan di dalamnya tautan ke file commitlint.js:
Perlihatkan bagian dari package.json { "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS -g './config/git/commitlint.js'" } }, "devDependencies": { "@commitlint/cli": "^7.2.1", "husky": "^1.1.3", }
- Buat file commitlint.js yang diperlukan agar linter berfungsi dengan benar. Tempatkan file yang dibuat di direktori ./config/git. Isi file:
Itu saja. Sekarang semua komit akan diperiksa sebelum mengirim ke repositori :)
Pastikan untuk melihat contoh utilitas commit yang dikonfigurasi
Jadi apa yang harus memilih komit atau komitmen?
Baik itu, dan yang lainnya! Bersama-sama, mereka membawa hasil yang sangat baik: yang pertama menghasilkan komit, yang kedua memeriksa mereka.
Mengapa standar merekomendasikan penggunaan imperatif?
Ini pertanyaan yang sangat menarik. Komit adalah perubahan kode, pesan dalam komit dapat dianggap sebagai instruksi untuk mengubah kode ini. Buat, ubah, tambah, perbarui, perbaiki - ini semua adalah instruksi khusus untuk pengembang.
Omong-omong, imperatif direkomendasikan dalam
sistem versi
Git itu sendiri :
[[imperative-mood]] Describe your changes in imperative mood, eg "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior.
Mengapa tetap berpegang pada konvensi? Apakah ini sepadan dengan waktu? Apa untungnya?
Layak. Secara umum, saya perhatikan bahwa kami menjadi lebih bersedia untuk merinci perubahan yang dilakukan pada basis kode. Dalam tubuh komit, kami menjelaskan secara rinci mengapa kami harus menggunakan ini atau solusi tersebut. Memahami sejarah menjadi lebih mudah secara objektif. Plus, produk kami sedang berkembang, dan kami mengharapkan penambahan dalam tim. Saya yakin bahwa berkat pengenalan standar dan otomatisasi, akan lebih mudah bagi para pemula untuk berintegrasi ke dalam proses pengembangan.
Coba dan bagikan hasilnya.
Tautan yang bermanfaat: