Haruskah saya menggunakan lampau atau present tense di git melakukan pesan? [Tutup]


531

Saya pernah membaca bahwa git commit harus dalam present imperense tense, misalnya "Tambahkan tes untuk x". Saya selalu menemukan diri saya menggunakan past tense, misalnya "Tes tambahan untuk x", yang terasa lebih alami bagi saya.

Berikut adalah komitmen John Resig baru-baru ini yang menampilkan pesan dua dalam satu:

Tweak beberapa set jQuery lagi hasil dalam tes manipulasi. Juga memperbaiki urutan hasil tes yang diharapkan.

Apakah itu penting? Yang mana yang harus saya gunakan?


12
Pertanyaan ini jadi perlu ditutup terutama berdasarkan opini . Lihat saja perbedaan pendapat antara imperatif dan past tense ! Yang sedang berkata, saya memilih imperative tense, karena itu sangat membantu memperjelas apa yang Anda lakukan ketika menulis ulang sejarah Anda, memetik ceri, menerapkan tambalan, dll!




3
@Eonil jika ditutup karena didasarkan pada opini di sini, juga akan ditutup untuk didasarkan pada opini.
ratchet freak

Jawaban:


601

Preferensi untuk pesan commit present-tense, style imperative datang dari Git sendiri. Dari Documentation / SubmittingPatches di repo Git:

Jelaskan perubahan Anda dalam mood imperatif, misalnya "make xyzzy do frotz", bukan "[patch ini] membuat xyzzy do frotz" atau "[Saya] mengubah xyzzy untuk melakukan frotz", seolah-olah Anda memberi perintah pada basis kode untuk mengubah tingkah laku.

Jadi, Anda akan melihat banyak Git melakukan pesan yang ditulis dengan gaya itu. Jika Anda bekerja pada tim atau perangkat lunak sumber terbuka, akan sangat membantu jika semua orang tetap pada gaya itu untuk konsistensi. Sekalipun Anda sedang mengerjakan proyek pribadi, dan Anda satu-satunya yang akan pernah melihat sejarah git Anda, akan sangat membantu jika Anda menggunakan mood imperatif karena ia membangun kebiasaan baik yang akan dihargai ketika Anda bekerja dengan orang lain.


90
Saya pikir ini adalah pilihan yang sangat baik. Pikirkan tentang apa itu komit, dalam bentuk berbeda: seperangkat instruksi untuk bagaimana beralih dari kondisi sebelumnya ke status baru. Sama seperti kata diff "tambahkan baris ini di sini, hapus baris ini di sini", pesan komit mengatakan dalam istilah kualitatif "buat perubahan ini". (Ya, git memang menyimpan komit hanya sebagai pohon dengan metadata, tetapi bagi manusia, bagian penting dari komit adalah diff.)
Cascabel

124
Anda dapat melihat komit sebagai seperangkat instruksi untuk bagaimana pergi dari negara sebelumnya ke negara baru; tapi saya melihatnya lebih sebagai check-point dalam evolusi kode. Bagi saya, pesan komit adalah log dari apa yang telah dilakukan pada kode sejak komit sebelumnya; dan untuk log, past tense jauh lebih masuk akal. Jika Anda benar-benar berpikir pesan komit harus berupa serangkaian instruksi, maka imperatif tegang adalah cara untuk pergi. Aku benar-benar tidak berpikir seperti itu.
karadoc

10
@oschrenk: Versi selanjutnya dari file tersebut telah memberikan alasan: "Jelaskan perubahan Anda dalam mood imperatif, misalnya 'make xyzzy do frotz' bukan '[patch ini] membuat xyzzy do frotz' atau '[Saya] mengubah xyzzy untuk melakukan frotz ', seolah-olah Anda memberi perintah pada basis kode untuk mengubah perilakunya. "
mipadi

44
Pesan komit harus imperatif, present tense karena dengan git Anda atau orang lain mungkin akhirnya melakukan rebaseatau cherry-pickdan dalam kasus itu, komit dapat digunakan di luar konteks aslinya. Akibatnya, pesan komit harus ditulis sendiri tanpa mengharapkan pembaca untuk melihat pesan komit di sekitarnya. Saat Anda memetik sakura, lebih masuk akal untuk menerapkan "Perbaiki algoritme quicksort" atau "Penyortiran: Tingkatkan kinerja" daripada "Perbaikan bug # 124" atau "Penyortiran yang dimodifikasi untuk meningkatkan kinerja".
Mikko Rantalainen

5
Cara saya berpikir tentang ini adalah bahwa pesan harus memberi tahu saya apa yang akan berubah jika saya memilih untuk menerapkan komit ini ke cabang saya. Saya tidak menganggapnya sebagai log tetapi sebagai keadaan bahwa saya dapat pindah ke dan saya perlu tahu apa yang akan terjadi ketika saya memilih negara tertentu.
steinybot

357

Proyek Anda hampir selalu harus menggunakan bentuk lampau . Bagaimanapun, proyek harus selalu menggunakan bentuk yang sama untuk konsistensi dan kejelasan.

Saya mengerti beberapa argumen lain yang berpendapat untuk menggunakan present tense, tetapi biasanya tidak berlaku. Poin-poin berikut ini adalah argumen umum untuk menulis dalam present tense, dan tanggapan saya.

  • Menulis dalam present tense memberi tahu seseorang apa yang akan dilakukan komit , daripada apa yang Anda lakukan.

Ini adalah alasan yang paling tepat yang ingin digunakan saat ini, tetapi hanya dengan gaya proyek yang tepat. Cara berpikir ini menganggap semua komitmen sebagai peningkatan atau fitur opsional, dan Anda bebas untuk memutuskan komitmen mana yang harus dipertahankan dan mana yang ditolak dalam repositori khusus Anda.

Argumen ini berfungsi jika Anda berurusan dengan proyek yang benar-benar didistribusikan. Jika Anda berurusan dengan proyek terdistribusi, Anda mungkin sedang mengerjakan proyek sumber terbuka. Dan itu mungkin proyek yang sangat besar jika benar-benar didistribusikan. Bahkan, itu mungkin kernel Linux atau Git. Karena Linux kemungkinan besar yang menyebabkan Git menyebar dan mendapatkan popularitas, mudah untuk memahami mengapa orang menganggap gayanya sebagai otoritas. Ya, gayanya masuk akal dengan kedua proyek itu. Atau, secara umum, ini bekerja dengan proyek-proyek besar, open source, didistribusikan .

Yang sedang berkata, sebagian besar proyek dalam kontrol sumber tidak bekerja seperti ini. Biasanya tidak benar untuk sebagian besar repositori. Ini adalah cara berpikir modern tentang komit: Subversion (SVN) dan repositori CVS hampir tidak dapat mendukung gaya check-in repositori ini. Biasanya cabang integrasi menangani penyaringan check-in yang buruk, tetapi yang umumnya tidak dianggap sebagai "opsional" atau "fitur yang bagus untuk dimiliki".

Dalam sebagian besar skenario, ketika Anda membuat komitmen ke repositori sumber, Anda menulis entri jurnal yang menjelaskan apa yang berubah dengan pembaruan ini, untuk memudahkan orang lain di masa depan untuk memahami mengapa perubahan dilakukan. Ini umumnya bukan perubahan opsional - orang lain dalam proyek ini diharuskan untuk menggabungkan atau membuat ulang. Anda tidak menulis catatan harian seperti "Dear diary, hari ini aku bertemu anak laki-laki dan ia mengatakan halo kepada saya.", Tapi malah Anda menulis "Saya bertemu anak laki-laki dan dia berkata halo kepada saya."

Akhirnya, untuk proyek-proyek yang tidak terdistribusi seperti itu, 99,99% waktu seseorang akan membaca pesan komit adalah untuk membaca sejarah - sejarah dibaca dalam bentuk lampau. 0,01% dari waktu itu akan memutuskan apakah mereka harus menerapkan komit ini atau mengintegrasikannya ke cabang / repositori mereka.

  • Konsistensi. Begitulah dalam banyak proyek (termasuk git itu sendiri). Juga alat git yang menghasilkan komit (seperti git merge atau git revert) melakukannya.

Tidak, saya jamin bahwa sebagian besar proyek yang pernah masuk dalam sistem kontrol versi memiliki sejarahnya di masa lalu (saya tidak punya referensi, tapi mungkin benar, mengingat argumen present tense baru sejak Git). Pesan "Revisi" atau komit pesan dalam present tense hanya mulai masuk akal dalam proyek yang benar-benar didistribusikan - lihat poin pertama di atas.

  • Orang tidak hanya membaca sejarah untuk mengetahui "apa yang terjadi pada basis kode ini", tetapi juga untuk menjawab pertanyaan seperti "apa yang terjadi ketika saya memilih komit ini", atau "hal-hal baru apa yang akan terjadi pada basis kode saya karena komitmen ini Saya mungkin atau mungkin tidak bergabung di masa depan ".

Lihat poin pertama. 99,99% dari waktu seseorang akan membaca pesan komit adalah untuk membaca sejarah - sejarah dibaca dalam bentuk lampau. 0,01% dari waktu itu akan memutuskan apakah mereka harus menerapkan komit ini atau mengintegrasikannya ke cabang / repositori mereka. 99,99% ketukan 0,01%.

  • Biasanya lebih pendek

Saya belum pernah melihat argumen yang baik yang mengatakan menggunakan tegang / tata bahasa yang tidak tepat karena lebih pendek. Anda mungkin hanya akan menyimpan 3 karakter rata-rata untuk pesan 50 karakter standar. Yang sedang berkata, present tense rata-rata mungkin akan menjadi beberapa karakter lebih pendek.

  • Anda dapat menyebutkan komit lebih konsisten dengan judul tiket di pelacak masalah / fitur Anda (yang tidak menggunakan bentuk lampau, meskipun terkadang di masa mendatang)

Tiket ditulis sebagai sesuatu yang saat ini sedang terjadi (mis. Aplikasi menunjukkan perilaku yang salah ketika saya mengklik tombol ini), atau sesuatu yang perlu dilakukan di masa depan (mis. Teks akan perlu ditinjau oleh editor).

Riwayat (mis. Pesan komit) ditulis sebagai sesuatu yang dilakukan di masa lalu (mis. Masalahnya telah diperbaiki).


79
Hari ini saya pertama kali mendengar tentang preferensi yang seharusnya dilakukan untuk gaya imperatif. Bagi saya, itu terdengar sangat tidak wajar dan aneh sehingga saya memutuskan untuk mencari pendapat lagi. Saya senang melihat saya bukan satu-satunya yang berpikir lampau lebih alami untuk melakukan pesan. :)
karadoc

57
git yang dihasilkan secara otomatis menggabungkan dan mengulang pesan komit sangat penting dan present tense ("Gabung", bukan "Digabung"; "Rebase", bukan "Rebased"), jadi Anda mungkin ingin mencocokkan ini dalam pesan komit Anda sendiri untuk konsistensi.
mjs

13
Tampaknya perbedaannya adalah antara fokus pada perubahan ke perangkat lunak - "Memperbaiki X dengan melakukan Y" - atau repositori - "Lakukan Y untuk memperbaiki X." +1 untuk argumen yang bagus, tapi saya pikir repo biasanya harus fokus pada dirinya sendiri daripada perangkat lunak yang dihasilkan.
l0b0

28
Masalahnya adalah, menggunakan imperatif, present tense works untuk proyek-proyek besar (misalnya Linux) sehingga jelas berskala. Selain itu, ini membutuhkan sedikit usaha nol menggunakan over past tense. Akibatnya, saya tidak melihat alasan (selain "orang tua digunakan untuk menulis pesan komit dalam bentuk lampau") untuk menggunakan hal lain selain keharusan, present tense. Jika Anda dapat mempelajari set perintah git, Anda dapat belajar menulis dengan imperatif, present tense.
Mikko Rantalainen

35
Imperatif bukan "baru sejak git". ChangeLog ada jauh sebelum git, dan penggunaan imperative selalu menjadi gaya yang direkomendasikan dalam Proyek GNU. gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
adl

81

Saya menulis deskripsi yang lebih lengkap tentang 365git .

Penggunaan imperatif, present tense adalah penggunaan yang sedikit membiasakan diri. Ketika saya mulai menyebutkannya, itu mendapat perlawanan. Biasanya sepanjang baris "Pesan komit mencatat apa yang telah saya lakukan". Tapi, Git adalah sistem kontrol versi terdistribusi di mana ada banyak tempat yang berpotensi untuk mendapat perubahan. Daripada menulis pesan yang mengatakan apa yang telah Anda lakukan; pertimbangkan pesan-pesan ini sebagai instruksi untuk apa yang akan dilakukan komit. Daripada memiliki komitmen dengan judul:

Renamed the iVars and removed the common prefix.

Miliki satu seperti ini:

Rename the iVars to remove the common prefix

Yang memberi tahu seseorang apa yang akan menerapkan komit, daripada apa yang Anda lakukan. Juga, jika Anda melihat histori repositori Anda, Anda akan melihat bahwa pesan yang dihasilkan Git juga ditulis dalam tegang ini - “Gabung” bukan “Digabung”, “Rebase” bukan “Diperbesar ulang” sehingga menulis dalam tegang yang sama membuat semuanya konsisten. Awalnya terasa aneh tetapi masuk akal (kesaksian tersedia saat mendaftar) dan akhirnya menjadi alami.

Setelah mengatakan semua itu - itu adalah kode Anda, repositori Anda: jadi siapkan panduan Anda sendiri dan patuhi itu.

Namun, jika Anda memutuskan untuk pergi dengan cara ini maka git rebase -idengan opsi reword akan menjadi hal yang baik untuk dilihat.


7
Nah, Anda telah mencampur dua pedoman berbeda: proyek open source Git, dan penggunaan reguler Git. Tautan yang disediakan tidak menyebutkan tegang sama sekali . Git doc resmi hanya menyebutkan batas 50 char. Git adalah VCS yang didistribusikan di mana ada banyak tempat untuk mendapatkan perubahan dari ... pertimbangkan pesan-pesan ini sebagai instruksi untuk apa yang akan dilakukan komit. Ini hanya berlaku untuk beberapa proyek yang sebenarnya merupakan proyek yang didistribusikan. 99,999% dari komitmen Git tidak akan pernah diterapkan secara manual seperti itu. Dalam sebagian besar proyek, sejarah adalah log perubahan, yang harus dalam bentuk lampau.
Matt Quigley

4
"dan harus melewati titik perhentian penuh"
takeshin

30

Tetap dengan imperatif present tense karena

  • itu baik untuk memiliki standar
  • itu cocok dengan tiket di pelacak bug yang secara alami memiliki bentuk "mengimplementasikan sesuatu", "memperbaiki sesuatu", atau "menguji sesuatu."

16

Untuk siapa Anda menulis pesan? Dan apakah pembaca biasanya membaca pesan sebelum atau sesudah kepemilikan dari komitmen itu sendiri?

Saya pikir jawaban yang baik di sini telah diberikan dari kedua perspektif, saya mungkin kurang menyarankan ada jawaban terbaik untuk setiap proyek. Suara split mungkin menyarankan sebanyak mungkin.

yaitu untuk meringkas:

  • Apakah pesannya terutama untuk orang lain, biasanya membaca di beberapa titik sebelum mereka menerima perubahan: Sebuah proposal tentang apa yang akan dilakukan perubahan terhadap kode yang ada.

  • Apakah pesannya didominasi sebagai jurnal / catatan untuk diri Anda sendiri (atau untuk tim Anda), tetapi biasanya membaca dari perspektif telah menerima perubahan dan mencari kembali untuk menemukan apa yang terjadi.

Mungkin ini akan memotivasi tim / proyek Anda.


10

apakah itu penting? orang-orang pada umumnya cukup pintar untuk menafsirkan pesan dengan benar, jika tidak, Anda mungkin tidak seharusnya membiarkan mereka mengakses repositori Anda!


27
Bagi sebagian orang , hal-hal seperti itu penting.
Wesley Murch

2
@mog, tautannya tidak membuat pernyataan apa pun tentang masa kini dan masa lalu.
ceving

2
Jika proyek ini berskala besar, orang-orang yang melakukan tinjauan kode dan perburuan bug akan melihat begitu banyak komitmen yang mereka butuhkan semua bantuan yang Anda dan saya bisa berikan. Tidak ada gunanya menyimpan beberapa detik sekarang untuk menyebabkan sakit kepala besar di masa depan karena tidak menulis pesan komit yang tepat.
Mikko Rantalainen

Saya tidak mengatakan jangan menulis pesan komit yang baik. Saya mengatakan tidak masalah jika Anda menggunakan lampau atau lampau.
Michael Baldry

1
Bagaimana Anda tahu, bahwa orang tersebut tidak dapat menafsirkan pesan komit Anda, adalah penyebab orang tersebut tidak cukup mampu, atau Anda tidak cukup mampu menulis pesan komit yang baik?
Haris

7

Ini terserah kamu. Cukup gunakan pesan komit sesuai keinginan. Tetapi lebih mudah jika Anda tidak beralih antara waktu dan bahasa.

Dan jika Anda berkembang dalam tim - itu harus didiskusikan dan ditetapkan tetap.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.