Пагадненне аб камітах 1.0.0

Сціслы агляд

Спецыфікацыя па дадаванню лёгкачытэльных паведамленняў у камітах для людзей і робатаў. Яно апісвае просты набор правілаў для стварэння зразумелай гісторыі камітаў, а таксама дазваляе прасцей распрацоўваць прылады аўтаматызацыі, заснаваныя на гісторыі камітаў. Дадзенае пагадненне сумяшчальна з Семантычным Версіянаваннем, апісваючы новыя функцыі, выпраўленні і змяненні, парушаючыя адваротную сумяшчальнасць паведамленняў камітаў.

Паведамленні камітаў павінны быць наступнай структуры:

<тып>[неабавязковы кантэкст]: <апісанне>

[неабавязковае цела]

[неабавязковая(ыя) зноска(і)]

Каміт змяшчае наступныя структурныя элементы для перадачы намераў карыстыльнікаў вашай бібліятэкі:

1. fix: каміт тыпу fix выпраўляе баг у вашам кодзе (адпавядае PATCH у Семантычным Версіянаванні).
2. feat: каміт тыпу feat дадае новую функцыю ў ваш код (адпавядае MINOR у Семантычным Версіянаванні).
3. BREAKING CHANGE: каміт, які мае зноску BREAKING CHANGE або каміт, які скончваецца клічнікам (!) пасля тыпу ці кантэксту, уводзячы змяненне(і), парушаючыя адваротную сумяшчальнасць (адпавядае MAJOR у Семантычным Версіянаванні). BREAKING CHANGE можа быць часткай каміту любога тыпу.
4. Іншыя тыпы камітаў дазволены. Напрыклад, @commitlint/config-conventional (заснаваны на пагадненні Angular) рэкамендуе build, chore, ci, docs, style, refactor, perf, test і іншыя.
5. Іншыя зноскі камітаў могуць быць аналягічны паведамленню git trailer format.

Дадатковыя тыпы не патрабуюцца «Пагадненню аб камітах» і ня маюць невідавочнага эфекту ў семантычным версіянаванні (калі толькі яны не ўключаюць BREAKING CHANGE). Кантэкст можа быць дададзены да тыпу каміту, каб даць дадатковую кантэкстную інфармацыю; яна трываецца ў дужках. Напрыклад, feat(parser): add ability to parse arrays.

Прыклады

Паведамленне каміту з апісаннем і зноскай BREAKING CHANGE

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

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

Паведамленне каміту з кантэкстам і ! для звяртання ўвагі на BREAKING CHANGE

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

Паведамленне каміту разам з ! і зноскай BREAKING CHANGE

chore!: drop support for Node 6

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

Паведамленне каміту бяз цела

docs: correct spelling of CHANGELOG

Паведамленне каміту з кантэкстам

feat(lang): add polish language

Паведамленне каміту с целам з некалькіх абзацаў і некалькімі зноскамі

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

Поўная Спецыфікацыя

Словы «MUST», «MUST NOT», «REQUIRED», «SHALL», «MAY» и «OPTIONAL» у дадзенам дакуменце павінна тлумачыцца як у RFC 2119.

1. Каміты павінны (MUST) пачынацца з тыпу, які з’яўляецца назоўнікам: feat, fix і г.д. За ім ідзе неабавязковы (OPTIONAL) кантэкст, неабавязковы (OPTIONAL) клічнік (!) і абавязковае (REQUIRED) двукроп’е (:) і прабел ( ).
2. Тып feat павінны (MUST) выкарыстоўвацца, калі каміт дадае новы функцыянал у ваша прыкладанне або вашу бібліятэку.
3. Тып fix павінны (MUST) выкарыстоўвацца, калі каміт выпраўляе баг у вашам прыкладанні ці ў вашай бібліятэцы.
4. Кантэкст можа (MAY) ісці пасля тыпу. Кантэкст павінны (MUST) быць назоўнікам, заключаным у круглыя дужкі, апісваючы частку кодавай базы, якую закрануў каміт. Напрыклад, fix(parser).
5. Апісанне павінна (MUST) ісці адразу пасля двукроп’я (:) і з прабелам ( ) пасля тыпу або кантэксту. Апісанне ўяўляе сабой сціслае выкладанне змен коду. Напрыклад, fix: array parsing issue when multiple spaces were contained in string.
6. Цела каміту можа (MAY) ісці пасля сціслага апісання, дадаючы дадатковую кантэкстную інфармацыю пра змены ў кодзе. Цела павінна (MUST) аддзяляцца ад апісання адным пустым радком.
7. Цела каміту мае самавольную форму и можа (MAY) складацца з любой колькасці абзацаў, падзеленых новым радком.
8. У адной ці некалькіх зносках можа (MAY) быць адзін пусты радок пасля цела. Кожная зноска павінна (MUST) складацца з токена слову, за якім ідзе раздзяляльнік :<прабел> ці <прабел>#, за якім ідзе радковае значэнне (заснавана на git trailer format).
9. Токен зноскі павінны (MUST) карыстаць - замест прабельных сымбаляў. Напрыклад, Acked-by (гэта дапамагае адрозніць раздзел зноскі ад яго цела, складаючагася з некалькіх абзацаў). Выключэнне складае BREAKING CHANGE, якое можа (MAY) таксама выкарыстоўвацца як токен.
10. Зноска можа (MAY) змяшчаць прабелы і сымбалі новага радку, а счытванне павінна (MUST) завяршацца пры выяўленні наступнай дапушчальнай пары токен-раздзяляльнік зноскі.
11. Крытычныя змяненні павінны (MUST) быць указаны ў тыпу, кантэксту або зносцы каміту.
12. Калі BREAKING CHANGE уключана ў зноску, то яно павінна (MUST) спалучацца з вялікіх літар ў тэксце BREAKING CHANGE, за якім ідзе двукроп’е (:), прабел ( ) і апісанне. Напрыклад, BREAKING CHANGE: environment variables now take precedence over config files.
13. Калі крытычныя змяненні знаходзяцца ў тыпу або кантэксту, то яны павінны (MUST) быць пазначаны клічнікам (!), непасрэдна перад двукроп’ем (:). Калі выкарыстоўваецца клічнік (!), то BREAKING CHANGE можа (MAY) быць апушчаны ў зносцы, а апісанне каміту павінна (SHALL) выкарыстоўвацца для апісання крытычнага змянення.
14. У вашых паведамленнях камітаў могуць (MAY) выкарыстоўвацца тыпы, адменныя ад feat і fix. Напрыклад, docs: updated ref docs.
15. Адзінкі інфармацыі, якія складаюць «Пагадненне аб камітах», не павінны (MUST NOT) апрацоўвацца распрацоўнікамі як адчувальныя да рэгістру, за выключэннем BREAKING CHANGE, каторае павінна (MUST) пісацца вялікімі літарамі.
16. BREAKING-CHANGE павінны (MUST) быць сінонімам BREAKING CHANGE пры выкарыстоўванні ў якасці токена ў зносцы.

Навошта выкарыстоўваць «Пагадненне аб камітах»

• Аўтаматычнае стварэнне спісаў змяненняў.
• Аўтаматычнае вызначэнне семантычнага павышэння версіі (на падставе тыпаў здзейсненых камітаў).
• Інфармаванне сябраў па камандзе, супольнасці і іншых зацікаўленых старон аб характары змяненняў.
• Запуск працэсаў зборкі і публікацыі.
• Спрасціце людзям удзел у вашых праектах, дазволіўшы ім вывучаць больш структураваную гісторыі камітаў.

FAQ (часта задаваныя пытанні)

Як мне абысціся з паведамленнямі камітаў на пачатковым этапе распрацоўкі?

Мы раім дзейнічаць так, быццам бы вы ўжо выпусцілі прадукт. Звычайна хтосьці, нават калі то вашыя калегі-распрацоўнікі праграмнага забеспячэння, карыстаецца вашым праграмным забеспячэннем. Яны пажадаюць ведаць, што выпраўлена, што ламаецца і г.д.

Тыпы ў загалоўку каміту павінны пісацца вялікімі ці маленікімі літарамі?

Выбярыце той, які вам больш падабаецца, і строга яго прытрымлівайцеся.

Што мне рабіць, калі каміт адпавядае больш чым аднаму тыпу?

Па магчымасці вярніцеся назад і зрабіце некалькі камітаў. Часткай перавагі «Пагаднення аб камітах» з’яўляецца здольнасць заахвочваць нас рабіць больш арганізаваныя каміты і PRs (pull requests, ці запыты на запросы на выцягванне).

Хіба то не перашкаджае інтэнсіўнай распрацоўцы і хуткай ітэрацыі?

Гэта перашкаджае хуткаму неарганізаванаму руху. Гэта дапаможа вам хутка прасоўвацца ў доўгатэрміновай перспектыве ў некалькіх праектах з рознымі ўдзельнікамі.

Ці можа «Пагадненне аб камітах» прывесці распрацоўнікаў да абмежавання тыпаў здзейсненых імі камітаў, таму што яны будуць думаць у адпаведнасці з дазволенымі тыпамі?

«Пагадненне аб камітах» схіляе нас рабіць больш вызначаных тыпаў камітаў, такіх, як fix. Акрамя гэтага, гібкасць «Пагаднення аб камітах» дазваляе вашай камандзе прыдумваць свае асабістыя тыпы і з цягам часу змяняць іх.

Як гэта звязана з Семантычным Версіянаваннем?

Каміты тыпу fix павінны быць пераведзены ў выпускі PATCH, feat — у MINOR, BREAKING CHANGE, незалежна ад тыпу, — у MAJOR.

Як мне давесці свае расшырэнні да спецыфікацыі «Пагадненне аб камітах». Напрыклад, @jameswomack/standard-commit-spec?

Мы раім выкарыстоўваць Семантычнае Версіянаванне для выпуску вашых уласных расшырэнняў для гэтай спецыфікацыі (і заклікаем вас ствараць гэтыя расшырэнні!).

Што мне рабіць, калі я выпадкова скарыстаў няправільны тып каміту?

Калі вы скарысталі няправільны тып, але адпаведны спецыфікацыі. Напрыклад, fix замест feat

Перад аб’яднаннем або выпускам памылкі мы раім выкарыстоўваць git rebase -i для рэдагавання гісторыі камітаў. Пасля выпуску рэдагаванне будзе адрознівацца ў залежнасці ад таго, якія прылады і працэсы вы выкарыстоўваеце.

Калі вы скарысталі тып, не прызначаны у спецыфікацыі. Напрыклад, feet замест feat

У горшым выпадку гэта ўсё яшчэ не канец свету, калі каміт не адпавядае спецыфікацыі «Пагаднення аб камітах». Гэта проста азначае, што каміт будзе прапушчаны прыладамі, заснаванымі на спецыфікацыі.

Ці ўсе мае ўдзельнікі павінны карыстацца спецыфікацыяй «Пагаднення аб камітах»?

Не! Калі вы выкарыстоўваеце рабочы працэс на падставе з’яднання (squash) камітаў у Git, то вядучыя спецыялісты па суправаджэнню могуць прывесці ў парадак паведамленні камітаў па меры іх зліцця (merge), не дадаючы нагрузкі для звычайных камітараў. Звычайны рабочы працэс для гэтага і заключаецца ў тым, каб ваша сістэма Git аўтаматычна з’яднала каміты з PR і прывяла форму для вядучага суправаджаючага, каб увесці найбольш падыходзячае паведамленне для зліцця.

Як «Пагадненне аб камітах» апрацоўвае скасаванне камітаў?

Скасаванне змяненняў коду можа быць складаным:

• Вы скасоўваеце змяненні некалькіх камітаў?
• Калі вы скасоўваеце змяненні новых функцый, ці павінны наступны выпуск быць патчам?

«Пагадненне аб камітах» ня робіць яўных спробаў вызначыць паводзіны скасавання змен. Замест гэтага мы пакідаем аўтарам прылад выкарыстоўваць гібкасць тыпаў і зносак для распрацоўкі сваёй лёгікі і для апрацоўкі скасавання змен.

Адна з парад — выкарыстоўваць тып revert і зноску, якая спасылаецца на касаваныя хэш-сумы камітаў. Напрыклад:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868