mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2024-11-15 10:55:16 +01:00
178 lines
15 KiB
Markdown
178 lines
15 KiB
Markdown
---
|
||
draft: false
|
||
aliases: ["/uk/"]
|
||
---
|
||
|
||
# Політика Комітів 1.0.0
|
||
|
||
## Вступ
|
||
|
||
Політика Комітів - це полегшена угода понад стандартними повідомленнями про коміти.
|
||
Вона надає легкий набір правил для створення зручної історії комітів;
|
||
що робить простішим процес написання автоматичних утиліт для цього.
|
||
Дана угода узгоджується з [Семантичними Версіями](https://semver.org/lang/uk/)
|
||
шляхом вказування можливостей, латок, та великих змін, зроблених в коміт повідомленнях
|
||
|
||
Повідомлення коміту має бути структуровано наступним чином:
|
||
|
||
|
||
---
|
||
|
||
```
|
||
<тип>[додатково]: <опис>
|
||
|
||
[необов'язково тіло]
|
||
|
||
[необов'язково додаток(тки)]
|
||
```
|
||
---
|
||
|
||
<br />
|
||
Коміт містить наступні елементи структури, для повідомлення інтенції для споживачів
|
||
вашої бібліотеки:
|
||
|
||
1. **fix:** коміт _типу_ `fix` виправляє ваду в вашому коді (це корелюється з [`PATCH`](https://semver.org/lang/uk/) в Семантичних Версіях).
|
||
2. **feat:** коміт _типу_ `feat` додає новий функціонал до коду (це корелюється з [`MINOR`](https://semver.org/lang/uk/) в Семантичних Версіях).
|
||
3. **BREAKING CHANGE:** коміт, що має додаток `BREAKING CHANGE:`, або суфікс `!` після типу, додає зміну в API (це корелюється з [`MAJOR`](https://semver.org/lang/uk/) в Семантичних Версіях).
|
||
BREAKING CHANGE може бути частиною будь-якого _type_.
|
||
4. _types_ інші ніж `fix:` та `feat:` дозволені, для прикладу [@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:`, та інші.
|
||
5. _footers_ інші ніж `BREAKING CHANGE: <опис>` можуть бути теж і наслідувати угоду схожу до
|
||
[git trailer format](https://git-scm.com/docs/git-interpret-trailers).
|
||
|
||
Додаткові типи не заборонені угодою про Політику Комітів, і не накладають додаткові умови в Семантичних Версія (окрім випадків коли вони містять BREAKING CHANGE).
|
||
<br /><br />
|
||
Область(сфера) може бути доданою до типу коміту в дужках, для надання додаткової контекстної інформації, наприклад `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
|
||
```
|
||
refactor!: drop support for Node 6
|
||
```
|
||
|
||
### Коміт повідомлення з контекстом та `!` аби привернути увагу до BREAKING CHANGE
|
||
```
|
||
refactor(runtime)!: drop support for Node 6
|
||
```
|
||
|
||
### Коміт повідомлення з `!` та BREAKING CHANGE додатком
|
||
```
|
||
refactor!: drop support for Node 6
|
||
|
||
BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.
|
||
```
|
||
|
||
### Коміт повідомлення без тіла
|
||
```
|
||
docs: correct spelling of CHANGELOG
|
||
```
|
||
|
||
### Коміт повідомлення з областю(сферою)
|
||
```
|
||
feat(lang): add polish language
|
||
```
|
||
|
||
### Коміт повідомлення з тілом з кількома абзацами і додатками
|
||
```
|
||
fix: correct minor typos in code
|
||
|
||
see the issue for details
|
||
|
||
on typos fixed.
|
||
|
||
Reviewed-by: Z
|
||
Refs #133
|
||
```
|
||
|
||
## Специфікація
|
||
|
||
Ключові слова “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, та “OPTIONAL” в цьому документі потрібно інтерпретувати як описано в [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
||
|
||
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. Тіло коміту - це вільна форма і може містити будь-яку кількість нових рядків і абзаців.
|
||
8. Один або два додатки MAY(можуть) бути надані після одного пустого рядка після тіла. Кожен додаток MUST(повинен) містити слово токен, після якого має бути або `:<space>` або `<space>#` роздільник, після якого має йти строкове значення (запозичено з
|
||
[git trailer convention](https://git-scm.com/docs/git-interpret-trailers)).
|
||
9. Токен додатка MUST(повинен) використовувати `-` на місці пропусків, наприкла, `Acked-by` ( це допомагає відрізнити додаток від тіла з багатьма параграфами. Виключення зроблене для `BREAKING CHANGE`, що MAY(може) також використовуватися як токен.
|
||
10. Значення додатку MAY(може) містити пропуски та нові рядки, і зчитування MUST(повинне) припинятися коли наступний коректний токен/роздільник додатку знайдено.
|
||
11. BREAKING CHANGE MUST(повинні) бути виділені в типі/області префіксі коміту, або як вміст додатку.
|
||
12. Якщо виділено в додатку, BREAKING CHANGE MUST(повинно) містити великими літерами BREAKING CHANGE, потім двокрапка, пропуск, та опис, наприклад,
|
||
_BREAKING CHANGE: environment variables now take precedence over config files_.
|
||
14. Якщо вставлене в типі/області префіксом, BREAKING CHANGE MUST(повинно) бути виділено `!` одразу перед `:`. Якщо `!` використане, `BREAKING CHANGE:` MAY(може) бути упущене в додатку, і опис коміту SHALL(має) бути використаний для опису BREAKING CHANGE.
|
||
15. Типи, інші за `feat` та `fix` MAY(можуть) бути використані в ваших коміт повідомленнях, наприклад, _docs: updated ref docs._
|
||
16. Одиниці інформації, що роблять Політику Комітів MUST NOT(не повинні) бути сприйняті як чутливими до регістру творцями інструментів, за виключенням BREAKING CHANGE, що MUST(мусить) бути великими літерами.
|
||
17. BREAKING-CHANGE MUST(повинно) бути синонімом до BREAKING CHANGE, коли використовується в додатку.
|
||
|
||
## Для чого використовувати Політику Комітів.
|
||
|
||
* Автоматичне створення Нотаток про Реліз(Changelog)
|
||
* Автоматичне визначення наступної версії в Семантичних Версіях(базуючись на типах комітів, що увійшли).
|
||
* Комунікування природи змін для команди, в публічному просторі, до власників.
|
||
* Запуск процесів компіляції та публікації.
|
||
* Полегшує людям шлях до контрибуції в ваш проєкт, надаючи їм більш структуровану історію комітів.
|
||
|
||
## ЧЗП
|
||
|
||
### Як потрібно поводити себе на початковій фазі розробки?
|
||
|
||
Рекомендуємо продовжувати так, наче ви вже створили реліз продукту. Типово *хтось*, навіть, якщо це ваші розробники, вже використовують ваше програмне забезпечення. Вони будуть знати, що виправлено, що поламано тощо.
|
||
|
||
### Як поводити себе з великими і малими літерами?
|
||
|
||
Будь-які можуть використовуватися, вле варто притримуватися якогось одного підходу.
|
||
|
||
### Що робити, якщо коміт підходить для кількох типів одночасно?
|
||
|
||
Зробіть декілька комітів, наскільки це можливо. Частина вигоди від Політики Комітів є можливість спонукати нас робити більш організовані коміти і PR/MRs
|
||
|
||
### Чи погіршує це швидку розробку і швидкі операції?
|
||
|
||
Погіршення відбувається в результаті неорганізованості. Дана Політика дає можливість рухатися швидше в довготривалій перспективі з різними контрибуторами.
|
||
|
||
### Чи може Політика Комітів спонукати розробників обмежуватися окремими типами комітів через відношення до цих типів?
|
||
|
||
Політика Комітів мотивує нас робити більше комітів по типу *виправлення*. Але Політика Комітів дає гнучкість з якою команда може створювати власні типи собі в зручність.
|
||
|
||
### Як це корелюється з Семантичними Версіями?
|
||
|
||
Тип `fix` має бути як `PATCH` релізами. Тип `feat` має бути як `MINOR` релізи. Коміти з `BREAKING CHANGE`, незалежно від типу мають йти в `MAJOR` релізи.
|
||
|
||
#### Коли використано тип із специфікації, але `fix` замість `feat`, як діяти?
|
||
|
||
Перед тим, як мержити і релізити помилку, ми рекомендуємо використовувати `git rebase -i` для редагування історії комітів. Після релізу однак, виправлення буде залежати від утиліт і процесів, які ви використовуєте в себе.
|
||
|
||
#### Якщо використано помилково тип не з специфікації, наприклад `feet` замість `feat`
|
||
|
||
В найгіршому випадку, це не є кінцем світу і коміт просто не буде враховано утилітами, бо вони про це нічого не знають.
|
||
|
||
### Чи всі мої контрибутори мають використовувати Політику Комітів згідно спеціфікації?
|
||
|
||
Ні! Якщо ви використовуєте політику об'єднання комітів, тоді в дане повідомлення лід може вписувати коміт згідно Політики Комітів, збагачуючи таким чином історію.
|
||
|
||
### Як Політика Комітів діє в якості повернення комітів(revert)?
|
||
|
||
Відновлення коду може бути насправді складним, особливо, якщо відновлюється багато комітів. Якщо повертається функціонал, наступний реліз має бути латкою чи релізом?
|
||
Політика Комітів ніяк не визначає поведінку щодо повернень коду. Ми залишаємо це на розсуд авторів відповідних утиліт для стратегії логіки, для чого можна використовувати типи та додатки.
|
||
|
||
Наша рекомендація - використовувати тип `revert`, і додаток, що зсилається на SHA комітів, які повертаються:
|
||
|
||
```
|
||
revert: let us never again speak of the noodle incident
|
||
|
||
Refs: 676104e, a215868
|
||
```
|