---
draft: false
aliases: ["/be/"]
---
# Пагадненне аб камітах 1.0.0
## Сціслы агляд
Спецыфікацыя па дадаванню лёгкачытэльных паведамленняў у камітах для людзей і робатаў.
Яно апісвае просты набор правілаў для стварэння зразумелай гісторыі камітаў, а таксама
дазваляе прасцей распрацоўваць прылады
аўтаматызацыі, заснаваныя на гісторыі камітаў. Дадзенае пагадненне сумяшчальна з
[Семантычным Версіянаваннем](https://semver.org/), апісваючы новыя функцыі, выпраўленні і
змяненні, парушаючыя адваротную сумяшчальнасць паведамленняў камітаў.
Паведамленні камітаў павінны быць наступнай структуры:
---
```
<тып>[неабавязковы кантэкст]: <апісанне>
[неабавязковае цела]
[неабавязковая(ыя) зноска(і)]
```
---
Каміт змяшчае наступныя структурныя элементы для перадачы намераў
карыстыльнікаў вашай бібліятэкі:
1. **fix:** каміт _тыпу_ `fix` выпраўляе баг у вашам кодзе (адпавядае
[`PATCH`](https://semver.org/#summary) у Семантычным Версіянаванні).
1. **feat:** каміт _тыпу_ `feat` дадае новую функцыю ў ваш код
(адпавядае [`MINOR`](https://semver.org/#summary) у Семантычным Версіянаванні).
1. **BREAKING CHANGE:** каміт, які мае _зноску_ `BREAKING CHANGE` або
каміт, які скончваецца клічнікам (`!`) пасля _тыпу_ ці
_кантэксту_, уводзячы змяненне(і), парушаючыя адваротную сумяшчальнасць
(адпавядае [`MAJOR`](https://semver.org/#summary) у Семантычным Версіянаванні).
`BREAKING CHANGE` можа быць часткай каміту любога _тыпу_.
1. Іншыя _тыпы_ камітаў дазволены. Напрыклад,
[@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (заснаваны
на [пагадненні Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) рэкамендуе `build`, `chore`,
`ci`, `docs`, `style`, `refactor`, `perf`, `test` і іншыя.
1. Іншыя _зноскі_ камітаў могуць быць аналягічны паведамленню [git trailer format](https://git-scm.com/docs/git-interpret-trailers).
Дадатковыя _тыпы_ не патрабуюцца «Пагадненню аб камітах» і ня маюць невідавочнага
эфекту ў семантычным версіянаванні (калі толькі яны не ўключаюць
`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](https://www.ietf.org/rfc/rfc2119.txt).
1. Каміты павінны (MUST) пачынацца з _тыпу_, які з'яўляецца назоўнікам:
`feat`, `fix` і г.д. За ім ідзе неабавязковы (OPTIONAL) _кантэкст_,
неабавязковы (OPTIONAL) клічнік (`!`) і абавязковае
(REQUIRED) двукроп'е (`:`) і прабел (` `).
1. _Тып_ `feat` павінны (MUST) выкарыстоўвацца, калі каміт дадае новы
функцыянал у ваша прыкладанне або вашу бібліятэку.
1. _Тып_ `fix` павінны (MUST) выкарыстоўвацца, калі каміт выпраўляе баг у
вашам прыкладанні ці ў вашай бібліятэцы.
1. _Кантэкст_ можа (MAY) ісці пасля _тыпу_. _Кантэкст_ павінны (MUST)
быць назоўнікам, заключаным у круглыя дужкі, апісваючы частку
кодавай базы, якую закрануў каміт. Напрыклад, `fix(parser)`.
1. _Апісанне_ павінна (MUST) ісці адразу пасля двукроп'я (`:`) і з прабелам
(` `) пасля _тыпу_ або _кантэксту_. _Апісанне_ ўяўляе сабой сціслае выкладанне змен коду. Напрыклад, `fix: array parsing issue when multiple
spaces were contained in string`.
1. _Цела_ каміту можа (MAY) ісці пасля сціслага _апісання_, дадаючы дадатковую кантэкстную інфармацыю пра змены ў кодзе. _Цела_ павінна
(MUST) аддзяляцца ад _апісання_ адным пустым радком.
1. _Цела_ каміту мае самавольную форму и можа (MAY) складацца з любой колькасці абзацаў, падзеленых новым радком.
1. У адной ці некалькіх _зносках_ можа (MAY) быць адзін пусты радок пасля
_цела_. Кожная _зноска_ павінна (MUST) складацца з токена слову, за якім
ідзе раздзяляльнік `:<прабел>` ці `<прабел>#`, за якім ідзе
радковае значэнне (заснавана на [git trailer format](https://git-scm.com/docs/git-interpret-trailers)).
1. Токен _зноскі_ павінны (MUST) карыстаць `-` замест прабельных сымбаляў.
Напрыклад, `Acked-by` (гэта дапамагае адрозніць раздзел _зноскі_ ад яго _цела_,
складаючагася з некалькіх абзацаў). Выключэнне складае `BREAKING CHANGE`,
якое можа (MAY) таксама выкарыстоўвацца як токен.
1. _Зноска_ можа (MAY) змяшчаць прабелы і сымбалі новага радку, а счытванне
павінна (MUST) завяршацца пры выяўленні наступнай дапушчальнай пары
токен-раздзяляльнік _зноскі_.
1. Крытычныя змяненні павінны (MUST) быць указаны ў _тыпу_, _кантэксту_ або
_зносцы_ каміту.
1. Калі `BREAKING CHANGE` уключана ў _зноску_, то яно павінна (MUST) спалучацца з
вялікіх літар ў тэксце `BREAKING CHANGE`, за якім ідзе двукроп'е (`:`),
прабел (` `) і _апісанне_. Напрыклад, `BREAKING CHANGE: environment
variables now take precedence over config files`.
1. Калі крытычныя змяненні знаходзяцца ў _тыпу_ або _кантэксту_, то яны павінны
(MUST) быць пазначаны клічнікам (`!`), непасрэдна перад двукроп'ем (`:`). Калі выкарыстоўваецца клічнік (`!`), то
`BREAKING CHANGE` можа (MAY) быць апушчаны ў _зносцы_, а _апісанне_ каміту павінна (SHALL) выкарыстоўвацца для апісання крытычнага змянення.
1. У вашых паведамленнях камітаў могуць (MAY) выкарыстоўвацца _тыпы_, адменныя ад
`feat` і `fix`. Напрыклад, `docs: updated ref docs`.
1. Адзінкі інфармацыі, якія складаюць «Пагадненне аб камітах», не павінны
(MUST NOT) апрацоўвацца распрацоўнікамі як адчувальныя да рэгістру, за
выключэннем `BREAKING CHANGE`, каторае павінна (MUST) пісацца вялікімі літарамі.
1. `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
```