Conventional Commits 1.0.0

Xulosa

Conventional Commits spetsifikatsiyasi - bu commit xabarlarni qanday yozish kerakligi haqidagi oddiy kelishuv. U tushunarli commitlar tarixini yaratish uchun oddiy qoidalar to’plamini taqdim etadi, shuningdek, commitlar tarixiga asoslangan avtomatlashtirish vositalarini ishlab chiqishni osonlashtiradi. Ushbu konventsiya SemVer bilan bog’liq bo’lib, commit xabarlarida kiritilgan yangi xususiyatlar, tuzatishlar va o’zgarishlarni ifodalaydi.

Commit xabari quyidagi tarzda tuzilishi kerak:

<tur>[ixtiyoriy kontekst]: <tasnif>

[ixtiyoriy tana (body)]

[ixtiyoriy so'ngi qism(lar) (footer(s))]

Commit kutubxonangiz foydalanuvchilariga mohiyatni yetkazish uchun quyidagi tarkibiy elementlarni o’z ichiga olishi kerak:

fix: fix commit turi - kodingizdagi xatoni tuzatadi (bu, Semantik Versiyalashtiruvdagi PATCH bilan mos keladi).
feat: feat commit turi - kodingizga yangi xususiyat qo’shadi. (bu, Semantik Versiyalashtiruvdagi MINOR bilan mos keladi).
BREAKING CHANGE: BREAKING CHANGE nomli footerga ega yoki <tur>[ixtiyoriy kontekst] dan so’ng undov belgisi (!) bilan tugallanadigan commit - amaldagi API ga nomutanosib o’zgartirish kiritadi (bu, Semantik Versiyalashtiruvdagi MAJOR bilan mos keladi). BREAKING CHANGE har qanday tur dagi commitlarning bir qismi bo’lishi mumkin.
Yuqorida ko’rsatilgan tur lardan boshqalariga ham ruxsat beriladi, masalan @commitlint/config-conventional (Angular konventsiyasi asosida) build:, chore:, ci:, docs:, style:, refactor:, perf:, test: , va boshqalar.
BREAKING CHANGE: <description> dan boshqa muqobil footerlardan foydalanish, hamda git trailer formatiga amal qilish mumkin.

Boshqa turlar Conventional Commits tomonidan talab qilinmaydi va Semantik versioning ga hech qanday aniq ta’sir ko’rsatmaydi (faqatgina BREAKING CHANGE ni o’z ichiga olishmasa). Commit turiga, qo’shimcha kontext qo’shish uchun turdan so’ng qavsdan foydalaning, masalan, feat(parser): add ability to parse arrays

Namunalar

`BREAKING CHANGE` footer ga hamda ta’rifga ega commit xabarlari

feat: allow provided config object to extend other configs

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

`BREAKING CHANGE` ni ifodalovchi `!` belgisiga ega commit xabarlari

feat!: send an email to the customer when a product is shipped

`BREAKING CHANGE` ni ifodalovchi `!` belgisi hamda kontekstga ega commit xabarlari

feat(api)!: send an email to the customer when a product is shipped

`BREAKING CHANGE` ni ifodalovchi `!` belgi va footerga ega commit xabarlari

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

tana(body) siz commit xabarlari

docs: correct spelling of CHANGELOG

kontekst ga ega commit xabarlari

feat(lang): add polish language

Bir nechta paragrafli tana(body) va bir nechta footer ga ega commit xabalari

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Spesifikatsiya

Ushbu hujjatdagi «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» kalit so’zlari RFC 2119 da ko’rsatilgandek talqin qilinishi kerak.

Commitlar ot so’z turkumiga oid, feat, fix va shunga o’xshash so’z bilan boshlanishi shart(MUST). Undan keyin ixtiyoriy kontekst (OPTIONAL), undov belgisi (!) (OPTIONAL), va undan so’ng ikki nuqta (:) hamda bo’sh joy ( ) joydan iborat bo’lishligi talab etiladi (REQUIRED).
Agar commit ilovangiz yoki kutubxonangizga yangi xususiyat qo’shsa, feat: turidan foydalanishingiz shart (MUST).
Agar commit ilovangiz yoki kutubxonangizdagi muommoni bartaraf qilsa, fix: turidan foydalanishingiz shart (MUST).
Turdan so’ng kontekst kelishi mumkin (MAY). Kontekst qavslar bilan o’ralgan, kutubxonangizdagi kodlarning bir qismini tavsiflovchi ot so’z turkumiga oid so’z bo’lishligi kerak, masalan fix(parser).
Commit haqida tavsif darhol tur/kontekst prefiksidan keyin ikki nuqta (:) va bo’sh joydan ( )keyin bo’lishi kerak (MUST). Tavsif bu kod o’zgarishlarining qisqacha xulosasidir. Masalan, fix: array parsing issue when multiple spaces were contained in string
Qisqa tavsifdan so’ng kod o’zgarishlari haqida qo’shimcha kontekstual ma’lumotlarni taqdim etuvchi tana(body) qismi taqdim etilishi mumkin (MAY). Tana(body) qismi tavsifdan keyin bitta bo’sh qatordan so’ng boshlanishi kerak (MUST).
Commitning tana(body) qismi ixtiyoriy bo’lib, istalgan miqdordagi paragraflardan iborat bo’lishi mumkin. (MAY)
Tana(body) qismidan keyin 1ta bo’sh qatordan so’ng, bir yoki bir nechta footerlar bo’lishligi mumkin (MAY). Har bir footer so’z belgisidan iborat bo’lishi, undan keyin :<bo'sh joy> yoki <bo'sh joy># ajratuvchisi, keyin matn qiymatidan iborat bo’lishligi shart (MUST) (git trailer format asosida).
Footer tokeni uchun ( ) bo’sh joy begilising o’rniga (-) dan foydalanish kerak (MUST). Masalan, Acked-by (bu footer tokenini uning ko’p paragrafli tana qismidan ajratishga yordam beradi). BREAKING CHANGE bundan mustasno, undan token sifatida ham foydalanish mumkin (MAY).
Footerning qiymati ya’ni tana qismida boʻshliqlar va yangi satrlar boʻlishi mumkin (MAY) va keyingi footer token/ajratuvchi juftlik kuzatilganda avvalgi footer tugatilishi kerak (MUST).
BREAKING CHANGE o’zgarishlar commit xabarining tur/kontekst prefiksida yoki footer token qismida ko’rsatilishi kerak (MUST).
Agar footerda BREAKING CHANGE bo’lsa, u katta harflardan tashkil topgan BREAKING CHANGE so’zlari va undan so’ng ikki nuqta (:), bo’sh joy ( ) va tavsifdan iborat bo’lishi kerak (MUST). Masalan, BREAKING CHANGE: environment variables now take precedence over config files.
Agar tur/kontekst prefiksida BREAKING CHANGE mavjud bo’lsa, u holda ikki nuqtadan (:) avval undov belgisi (!) bo’lishligi shart (MUST)! Agar undov belgisi (!) ishlatilgan bo’lsa, u holda footer qismida emas (MAY), balki commit xabarining tasnif qismida BREAKING CHANGE haqida ma’lumot berilishi mumkin. (SHALL)
Commit xabarlarida feat va fixdan boshqa turlardan foydalanish mumkin (MAY). Masalan, docs: updated ref docs
“Conventional Commits” kelishuviga asosan ishlatilayotgan so’zlar, dasturchilar tomonidan case sensitive bo’lmasligi kerak (MUST NOT), lekin BREAKING CHANGE bundan mustasno, chunki bu katta harflarda yozilishi lozim (MUST).
BREAKING-CHANGE, footerning tokeni sifatida ishlatilganda, BREAKING CHANGE bilan sinonim bo‘lishi kerak (MUST).

Nima uchun «Conventional Commits» dan foydalanish kerak

Avtomatik tarzda o’zgarishlar ro’yhati(CHANGELOG) yaratilishi.
Semantik versiyani avtomatik ravishda aniqlash (qo’shilgan commitlarning turlariga asoslanib).
Jamoadoshlarni, ommani va boshqalarni o’zgarishlarning mohiyati haqida xabardor qilish.
Build hamda Publish jarayonlarini ishga tushirish.
Yaxshi tuzilgan commitlar tarixini o’rganish orqali, odamlarga sizning loyihalaringizga hissa qo’shishni osonlashtirish imkonini beradi.

FAQ (Tez-tez so’raladigan savollar)

Boshlang’ich rivojlantirish bosqichida commit xabarlari bilan qanday munosabatda bo’lish kerak?

Biz, siz mahsulotni allaqachon ishlab chiqarilgan deb davom etishingizni tavsiya qilamiz. Odatda kimdir, garchi u sizning dastur ishlab chiquvchi hamkasbingiz bo’lsa ham, sizning dasturingizdan foydalanadi. Ular, tuzatilgan narsalar, nimalar qo’shilganligi va h.k haqida xabardor bo’lishni istaydilar.

Commit turi katta yoki kichik harflarda bo’lishi kerakmi?

Sizga eng yoqqanini tanlang va unga qat’iy rioya qiling.

Agar commit birdan ko’p commit turlariga mos keladigan bo’lsa nima qilish kerak?

Iloji bo’lsa, orqaga qayting va bir nechta commitlarni yarating. Conventional Commitsning afzalliklaridan biri bu bizni ko’proq tashkillashtirilgan commitlar va PR (Pull Request) qilishga undash qobiliyatidir.

Bu tez rivojlanish va tez iteratsiyaga to’sqinlik qilmaydimi?

Bu tez, tartibsiz harakatni oldini oladi. Bu sizga turli hissa qo’shuvchilar bilan bir nechta loyihalar bo’ylab tez uzoq muddatli harakat qilish imkonini beradi.

`«Conventional Commits»` dasturchilarni o’zlari bajaradigan commitlar turlarini cheklashga olib kelishi mumkinmi, chunki ular tavsiya etilgan turlarga ko’ra o’ylashadi?

Conventional Commits bizni tuzatishlar (fix: ) kabi muayyan turdagi commitlarni ko’proq qilishga undaydi. Bundan tashqari, Conventional Commitsning moslashuvchanligi sizning jamoangizga o’z turlarini ishlab chiqishga va vaqt o’tishi bilan bu turlarni o’zgartirishga imkon beradi.

Buni Semantik versiyaga qanday aloqasi bor?

fix turidagi commitlar PATCH relizlariga, feat - MINOR-ga, BREAKING CANGE - turidan qat’iy nazar - MAJOR-ga tarjima qilinishi kerak.

Qanday qilib kengaytmalarimni(extensions) «Conventional Commits» spetsifikatsiyasiga moslashtirishim kerak, masalan. `@jameswomack/conventional-commit-spec`?

Ushbu spetsifikatsiyaga o’z kengaytmalaringizni chiqarish uchun Semantik versiyadan foydalanishni tavsiya etamiz (va sizni ushbu kengaytmalarni yaratishga undaymiz!).

Agar tasodifan noto’g’ri commit turidan foydalansam nima qilishim kerak?

Siz spetsifikatsiyaga tegishli, lekin to’g’ri turdan foydalanmaganingizda, masalan. `feat` o’rniga `fix`

Xatoni push yoki releasing qilishdan oldin, biz commitlar tarixini tahrirlash uchun git rebase -i dan foydalanishni tavsiya qilamiz. Release so’ng, tahrirlash qaysi vositalar va jarayonlardan foydalanganingizga qarab o’zgaradi.

Spetsifikatsiyada ko’rsatilmagan turdan foydalanganda. Misol uchun, `feat` o’rniga `feet`

Eng yomon holatga ko’ra, agar commit Conventional Commits spetsifikatsiyasiga to’g’ri kelmasa, bu qiyomat degani emas. Bu shunchaki spetsifikatsiyaga asoslangan vositalar tomonidan commit o’tkazib yuborilishini anglatadi.

Mening barcha kontributorlarim `Conventional Commits` spetsifikatsiyasidan foydalanishlari kerakmi?

Yo’q! Agar siz Gitda commitlarni birlashtirish (squash) usulidan foydalansangiz, loyiha maintainerlari birlashtirilgan, oddiy commit qiluvchilarning ish yukini qo’shmasdan birlashtirishi, topshiriq xabarlarini tartibga solishi mumkin. Buning uchun umumiy ish jarayoni sizning git tizimingiz avtomatik ravishda PR soʻrovi boʻyicha commitlarni squash qilish va maintainerga birlashtirish uchun tegishli git commit xabarini kiritadigan formani taqdim qilishi kerak.

«Conventional Commits» orqali qanday qilib bekor qilingan commitlarni uzatish mumkin?

Kod o’zgarishlarini bekor qilish qiyin bo’lishi mumkin:

Bir nechta commitlarni bekor qilyabsizmi?
Agar siz yangi xususiyat o’zgarishlarini bekor qilsangiz, keyingi versiya PATCH bo’lishi kerakmi?

Conventional Commits bekor qilish xatti-harakatini aniqlash uchun aniq tarzda ta’riflashga urinmaydi. Buning o’rniga, biz o’zgarishlarni bekor qilish uchun o’z mantig’ini ishlab chiqishda turlar va footerlarning moslashuvchanligidan foydalanishni vosita mualliflariga qoldiramiz.

Tavsiyalardan biri revert turi va qaytarilayotgan majburiyat xeshlariga (SHA) ishora qiluvchi footerdan foydalanishdir. Masalan:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

Conventional Commits