Політика Комітів 1.0.0

Вступ

Політика Комітів - це полегшена угода понад стандартними повідомленнями про коміти. Вона надає легкий набір правил для створення зручної історії комітів; що робить простішим процес написання автоматичних утиліт для цього. Дана угода узгоджується з Семантичними Версіями шляхом вказування можливостей, латок, та великих змін, зроблених в коміт повідомленнях

Повідомлення коміту має бути структуровано наступним чином:

<тип>[додатково]: <опис>

[необов'язково тіло]

[необов'язково додаток(тки)]

Коміт містить наступні елементи структури, для повідомлення інтенції для споживачів вашої бібліотеки:

fix: коміт типу fix виправляє ваду в вашому коді (це корелюється з PATCH в Семантичних Версіях).
feat: коміт типу feat додає новий функціонал до коду (це корелюється з MINOR в Семантичних Версіях).
BREAKING CHANGE: коміт, що має додаток BREAKING CHANGE:, або суфікс ! після типу, додає зміну в API (це корелюється з MAJOR в Семантичних Версіях). BREAKING CHANGE може бути частиною будь-якого type.
types інші ніж fix: та feat: дозволені, для прикладу @commitlint/config-conventional (базовано на Angular домовленостях) рекомендовані build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, та інші.
footers інші ніж BREAKING CHANGE: <опис> можуть бути теж і наслідувати угоду схожу до 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”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, та “OPTIONAL” в цьому документі потрібно інтерпретувати як описано в RFC 2119.

Коміти MUST(повинні) бути з префіксом типу, що складається з іменника feat, fix, тощо., наступним йде OPTIONAL(необов’язково) область(сфера), OPTIONAL(необов’язково) !, та REQUIRED(обов’язково) завершити двокрапкою та пропуском.
Тип feat MUST(повинен) використовуватися, коли коміт додає новий функціонал в ваш додаток або бібліотеку.
Тип fix MUST(повинен) використовуватися якщо коміт є латкою для вашого додатку.
Область(сфера) MAY(може) бути вказана після типу. Область(сфера) MUST(повинна) містити іменник, що описує секцію коду виділену лапками, наприклад, fix(parser):
Опис MUST(повинен) одразу завершатися двокрапкою і пропуском після області(сфери). Опис - це короткий підсумок змін в коді, наприклад, fix: array parsing issue when multiple spaces were contained in string.
Довге тіло коміту MAY(може) бути додано після короткого опису, надаючи додаткову контекстну інформацію про зміни в коді. Тіло MUST(повинне) починатися з однієї пустої строки після опису.
Тіло коміту - це вільна форма і може містити будь-яку кількість нових рядків і абзаців.
Один або два додатки MAY(можуть) бути надані після одного пустого рядка після тіла. Кожен додаток MUST(повинен) містити слово токен, після якого має бути або :<space> або <space># роздільник, після якого має йти строкове значення (запозичено з git trailer convention).
Токен додатка MUST(повинен) використовувати - на місці пропусків, наприкла, Acked-by ( це допомагає відрізнити додаток від тіла з багатьма параграфами. Виключення зроблене для BREAKING CHANGE, що MAY(може) також використовуватися як токен.
Значення додатку MAY(може) містити пропуски та нові рядки, і зчитування MUST(повинне) припинятися коли наступний коректний токен/роздільник додатку знайдено.
BREAKING CHANGE MUST(повинні) бути виділені в типі/області префіксі коміту, або як вміст додатку.
Якщо виділено в додатку, BREAKING CHANGE MUST(повинно) містити великими літерами BREAKING CHANGE, потім двокрапка, пропуск, та опис, наприклад, BREAKING CHANGE: environment variables now take precedence over config files.
Якщо вставлене в типі/області префіксом, BREAKING CHANGE MUST(повинно) бути виділено ! одразу перед :. Якщо ! використане, BREAKING CHANGE: MAY(може) бути упущене в додатку, і опис коміту SHALL(має) бути використаний для опису BREAKING CHANGE.
Типи, інші за feat та fix MAY(можуть) бути використані в ваших коміт повідомленнях, наприклад, docs: updated ref docs.
Одиниці інформації, що роблять Політику Комітів MUST NOT(не повинні) бути сприйняті як чутливими до регістру творцями інструментів, за виключенням BREAKING CHANGE, що MUST(мусить) бути великими літерами.
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

Політика Комітів