Komit Konvensional

Spesifikasi untuk menambahkan makna yang dapat dibaca manusia dan mesin untuk pesan komit

Conventional Commits 1.0.0-beta.4

Ringkasan

Conventional Commits adalah perjanjian sederhana tentang cara menulis pesat komit. Ini menjelaskan sekumpulan aturan sederhana untuk membuat riwayat komit yang jelas; yang memudahkan untuk membuat alat automatis di atasnya. Perjanjian ini cocok dengan SemVer, dengan menjelaskan suatu fitur (features), perbaikan (fixes), merusak perubahan (breaking changes) yang dimuat dalam pesan komit.

Pesan komit harus tersusun sebagai berikut:


<type>[optional scope]: <description>

[optional body]

[optional footer]

Komit berisi elemen struktural sebagai berikut, untuk menyampaikan maksud kepada konsumen perpustakaan anda:

  1. fix: komit tipe fix untuk perbaikan celah (bug) dalam kode anda (ini berkolerasi dengan PATCH di semantic versioning).
  2. feat: komit tipe feat memperkenalkan suatu fitur (feature) baru dalam kode anda (ini berkolerasi dengan MINOR di semantic versioning).
  3. BREAKING CHANGE: komit yang berisi teks BREAKING CHANGE: di awal bagian opsi badan atau kaki mengenalkan merusak perubahan API (ini berkolerasi dengan MAJOR di semantic versioning). BREAKING CHANGE dapat menjadi bagian dari komit tipe apapun.
  4. Lainya: komit dengan tipe-tipe selain dari fix: and feat: diperbolehkan, misalnya @commitlint/config-conventional (berdasarkan pada Angular convention) direkomendasikan chore:, docs:, style:, refactor:, perf:, test:, dan lainya.

Kami juga merekomendasikan improvement untuk komit yang meningkatkan implementasi saat ini tanpa menambahkan fitur baru atau memperbaiki celah (bug). Perhatikan bahwa tipe-tipe ini tidak di amanatkan oleh spesifikasi conventional commits, dan tidak ada efek implisit dalam semantic versioning (kecuali mereka termasuk BREAKING CHANGE). Cakupan dapat disediakan ke tipe komit. untuk memberikan informasi kontekstual tambahan dan terkandung dalam kurung, misalnya, feat(parser): add ability to parse arrays.

Examples

Pesan komit dengan deskripsi dan breaking change di badan

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Pesan komit dengan opsi ! untuk menarik perhatian pada breaking change

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

Pesan komit tanpa badan

docs: correct spelling of CHANGELOG

Pesan komit dengan cakupan

feat(lang): add polish language

Pesan komit untuk perbaikan menggunakan (opsi) nomor masalah.

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

Spesifikasi

Kata “HARUS”, “TIDAK BOLEH”, “DIBUTUHKAN”, “SEHARUSNYA”, “JANGAN SAMPAI”, “SEBAIKNYA”, “SEBAIKNYA TIDAK”, “DIREKOMENDASIKAN”, “BISA”, dan “OPSIONAL” di dokumen ini sesuai dengan RFC 2119.

  1. Komit HARUS (MUST) diawali dengan tipe, yang terdiri dari kata benda, feat, fix, dll., diikuti dengan OPSIONAL (OPTIONAL) cakupan, dan DIBUTUHKAN terminal colon dan spasi.
  2. tipe feat HARUS (MUST) digunakan ketika komit menambahkan fitur baru ke apilkasi atau perpustakaan anda.
  3. tipe fix HARUS (MUST) digunakan ketika komit mewakili perbaikan celah (bug) untuk aplikasi anda.
  4. Cakupan BISA (MAY) disediakan setelah tipe. Cakupan HARUS terdiri dari kata benda yang menggambarkan bagian dari kode yang dikelilingi tanda kurung, misalnya, fix(parser):
  5. Deskripsi HARUS (MUST) segera mengikuti spasi setelah awalan tipe/cakupan. Deskripsi adalah ringkasan singkat dari perubahan kode, misalnya, fix: array parsing issue when multiple spaces were contained in string.
  6. Komit badan yang leibh panjang BISA (MAY) disediakan setelah deskripsi pendek, memberikan informasi kontekstual tambahan tentang perubahan kode. Badan HARUS (MUST) diawalin dengan satu barus kosong setelah deskripsi.
  7. Kaki satu atau lebih baris BISA (MAY) disediakan satu baris kosong setelah badan. kaki HARUS (MUST) berisi tentang meta-informasi tentang perubahan, misalnya, related pull-requests, reviewers, breaking changes, dengan satu informasi meta per baris.
  8. Breaking changes HARUS (MUST) di tunjukan di bagian paling awal dari bagian tubuh, atau di awal baris di bagian kaki. Breaking change HARUS terdiri dari huruf besar BREAKING CHANGE, diikuti dengan colon dan spasi.
  9. Deskripsi HARUS (MUST) disediakan setelah BREAKING CHANGE: , menggambarkan apa yang telah berubah tentang API, misalnya, BREAKING CHANGE: environment variables now take precedence over config files.
  10. Tipe selain feat dan fix BISA (MAY) digunakan dalam pesan komit anda.
  11. Unit-unit informasi yang membentuk conventional commits TIDAK BOLEH (MUST NOT) diperlakukan case sensitif oleh pelaksana, dengan pengecualian BREAKING CHANGE yang HARUS (MUST) huruf besar.
  12. ! BISA (MAY) ditambakan sebelum : dalam awalan tipe/cakupan, untuk menarik perhatian pada breaking changes. BREAKING CHANGE: description HARUS (MUST) dimasukan kedalam badan atau kaki,bersama dengan ! di awalan.

Mengapa menggunakan Conventional Commits

FAQ

Bagaimana saya harus berurusan dengan pesan komit pada fase pengembangan awal?

Kami menyarankan Anda melanjutkan seolah-olah Anda sudah merilis produk. Biasanya seseorang, bahkan jika itu sesama pengembang perangkat lunak Anda, menggunakan perangkat lunak Anda. Mereka ingin tahu apa yang diperbaiki, apa yang rusak, dll.

Apakah tipe dalam komit judul huruf besar atau kecil?

Casing apa pun dapat digunakan, tetapi yang terbaik adalah konsisten.

Apa yang harus saya lakukan jika komit sesuai dengan lebih dari satu tipe komit?

Kembalilah dan buat beberapa komit kapan pun memungkinkan. Bagian dari manfaat Conventional Commits adalah kemampuannya mendorong kami untuk membuat komitmen dan PR yang lebih terorganisir.

Tidakkah ini menghambat pengembangan yang cepat dan iterasi yang cepat?

Ini mencegah bergerak cepat dengan cara yang tidak teratur. Ini membantu Anda dapat bergerak cepat jangka panjang di berbagai proyek dengan kontributor yang bervariasi.

Mungkinkah Komitmen Konvensional membuat pengembang membatasi jenis komitmen yang mereka buat karena mereka akan memikirkan jenis yang disediakan?

Komitmen Konvensional mendorong kita untuk membuat lebih banyak jenis komitmen tertentu seperti perbaikan. Selain itu, fleksibilitas Komitmen Konvensional memungkinkan tim Anda untuk membuat tipe mereka sendiri dan mengubah tipe-tipe itu seiring waktu.

Bagaimana ini berhubungan dengan SemVer?

Komit tipe fix harus diterjemahkan ke rilis PATCH. Komit tipe feat harus diterjemahkan ke rilis MINOR. Komit dengan BREAKING CHANGE dalam komit, apa pun jenisnya, harus diterjemahkan ke rilis MAJOR.

Bagaimana cara saya memberi versi ekstensi saya ke Spesifikasi Komitmen Konvensional, mis. @jameswomack/commit-spec-konvensional?

Kami sarankan menggunakan SemVer untuk merilis ekstensi Anda sendiri ke spesifikasi ini (dan mendorong Anda untuk membuat ekstensi ini!)

Apa yang harus saya lakukan jika saya secara tidak sengaja menggunakan tipe komit yang salah?

Saat Anda menggunakan jenis yang memiliki spesifikasi tetapi bukan jenis yang benar, misalnya, fix bukan feat

Sebelum menggabungkan atau merilis kesalahan, sebaiknya gunakan git rebase -i untuk mengedit riwayat komit. Setelah rilis, pembersihan akan berbeda sesuai dengan alat dan proses apa yang Anda gunakan.

Saat Anda menggunakan jenis bukan spesifikasi, mis. feet bukannya feat

Dalam skenario terburuk, ini bukan akhir dunia jika komit mendarat yang tidak memenuhi spesifikasi conventional commit. Ini berarti komit akan dilewatkan oleh alat yang didasarkan pada spesifikasi.

Apakah semua kontributor saya perlu menggunakan spesifikasi commit konvensional?

Tidak! Jika Anda menggunakan alur kerja berbasis squash di pengelola Git dapat membersihkan pesan komit saat mereka digabung — menambahkan tidak ada beban kerja ke komuter biasa. Alur kerja umum untuk ini adalah membuat sistem git Anda secara otomatis squash melakukan dari permintaan tarikan dan menyajikan formulir bagi pengelola utama untuk memasukkan pesan git commit yang tepat untuk penggabungan.