diff --git a/config.yaml b/config.yaml index 87acdc7..8715353 100755 --- a/config.yaml +++ b/config.yaml @@ -313,3 +313,20 @@ languages: current: v1.0.0 list: - v1.0.0 + + be: + weight: 17 + languageName: "Belarusian - Беларуская" + title: Пагадненне аб камітах + description: Спецыфікацыя па дадаванню лёгкачытэльных паведамленняў у камітах для людзей і робатаў + actions: + - label: Сціслы агляд + url: '#сціслы-агляд' + - label: Поўная Спецыфікацыя + url: '#поўная-спецыфікацыя' + - label: Github + url: 'https://github.com/conventional-commits/conventionalcommits.org' + versions: + current: v1.0.0 + list: + - v1.0.0 diff --git a/content/v1.0.0/index.be.md b/content/v1.0.0/index.be.md new file mode 100644 index 0000000..9e46740 --- /dev/null +++ b/content/v1.0.0/index.be.md @@ -0,0 +1,241 @@ +--- +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 +```