conventionalcommits.org/content/v1.0.0/index.uk.md

draft	aliases
false	/uk/

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

Вступ

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

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

---

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

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

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

---

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

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

refactor!: 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.

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).
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.
13. Якщо вставлене в типі/області префіксом, BREAKING CHANGE MUST(повинно) бути виділено ! одразу перед :. Якщо ! використане, BREAKING CHANGE: MAY(може) бути упущене в додатку, і опис коміту SHALL(має) бути використаний для опису BREAKING CHANGE.
14. Типи, інші за feat та fix MAY(можуть) бути використані в ваших коміт повідомленнях, наприклад, docs: updated ref docs.
15. Одиниці інформації, що роблять Політику Комітів MUST NOT(не повинні) бути сприйняті як чутливими до регістру творцями інструментів, за виключенням BREAKING CHANGE, що MUST(мусить) бути великими літерами.
16. 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

Про цей документ

Політика комітів створена в більшості своїй з Angular Commit Guidelines.

Перша чернетка була створена спільними зусиллями нижчевказаних:

• conventional-changelog: a set of tools for parsing Conventional Commits messages from git histories.
• parse-commit-message: Extensible utilities for parsing, stringify and validating Conventional Commit messages.
• bumped: a tool for releasing software that makes it easy to perform actions before and after releasing a new version of your software.
• unleash: a tool for automating the software release and publishing lifecycle.
• lerna: a tool for managing monorepos, which grew out of the Babel project.

Інструменти для Політики Комітів

• go-conventionalcommits: Full Go powers to parse conventional commits
• go-conventional-commit: go library for parsing commit messages following the specification.
• chglog: a tool for parsing Conventional Commits messages from git histories and turning them into templateable change logs.
• fastlane-plugin: follows the specification to manage versions and generate a changelog automatically
• commitizen/cz-cli: A Node.js tool to create commit messages following the Conventional Commits specs.
• commitizen-tools/commitizen: A tool written in Python to create commiting rules for projects, auto bump versions and auto changelog generation.
• php-commitizen: A PHP tool built to create commit messages following the Conventional Commits specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects.
• php-conventional-changelog: a tool built to generate a changelog from a project's committing history messages and metadata and automate versioning with Semver, following Conventional Commits specs. Configurable and usable for PHP projects as a composer dependency or usable globally for non-PHP projects.
• commitlint: A linter to check that your commit messages meet the Conventional Commits format.
• gitlint: Git commit message linter written in Python, which can be configured to enforce Conventional Commits format.
• conform: a tool that can be used to enforce policies on git repositories, including Conventional Commits.
• detect-next-version: Parse, detect and get more metadata about given Conventional Commits.
• recommended-bump: Calculcates the recommended version bump based on given Conventional Commits.
• git-commits-since: Get all (raw) commits since period or (by default) from latest git SemVer tag, plus plugins support.
• standard-version: Automatic versioning and CHANGELOG management, using GitHub's new squash button and the recommended Conventional Commits workflow.
• Conventional Commit: provides extensible context and template-based completion, and inspections, for Conventional Commits inside the VCS Commit dialog. Available for all JetBrains IDEs.
• Git Commit Template: Add Conventional Commits support to JetBrains Editors (IntelliJ IDEA, PyCharm, PhpStorm...).
• commitsar: Go tool for checking if commits on branch are Conventional Commits compliant. Comes with Docker image for CI uses.
• semantic-release: A tool that automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
• python-semantic-release: Automatic Semantic Versioning for Python projects. This is a Python implementation of the semantic-release for Node.js.
• VSCode Conventional Commits: Add Conventional Commits supports for VSCode.
• Pyhist: A Python utility to automagically update the package version from the git history and generate the Changelog.
• git-mkver: A tool to automatically apply Semantic Versioning to git repositories based on Conventional Commits.
• Conventional Commits Next Version: A tooling and language agnostic utility to calculate the next semantic version based on the Conventional Commits since the prior version. Supports monorepos.
• change: A tool for generating and updating a changelog using Conventional Commits.
• Turbogit: A command line tool to help you follow Conventional Commits flow.
• sv4git: A command line tool (CLI) to validate commit messages, bump versions, create tags and generate changelogs.
• Versio: A monorepo-compatible tool that updates version numbers based on conventional commits and project dependencies. It can generate tags and changelogs, too.
• Git Changelog Lib: A Java library that supports rendering a changelog given a context derived from Git. Supports conventional commits with Handlebars Helpers. It is used in:
  • Gradle
  • Maven
  • Jenkins
  • Command Line

Проєкти, що використовують Політику Комітів

• NFPM: NFPM is Not FPM - a simple deb, rpm and apk packager written in Go
• yargs: everyone's favorite pirate themed command line argument parser.
• istanbuljs: a collection of open-source tools and libraries for adding test coverage to your JavaScript tests.
• uPortal-home and uPortal-application-framework: Optional supplemental user interface enhancing Apereo uPortal.
• massive.js: A data access library for Node and PostgreSQL.
• electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS.
• scroll-utility: A simple to use scroll utility package for centering elements, and smooth animations
• Blaze UI: Framework-free open source UI toolkit.
• Monica: An open source personal relationship management system.
• mhy: A zero-config, out-of-the-box, multi-purpose toolbox and development environment.
• @tandil/diffparse: Simple parser for Diff files (unified diff format).
• @tandil/diffsplit: Easy split of .diff & .patch into its files.
• @thi.ng/umbrella: Monorepo of ~100 TypeScript projects for data driven development
• yii2-basic-firestarter: 🔥 An enhanced Yii2 app template.
• dcyou/resume: 😎 Template to easily and quickly create your online CV.
• Nintex Forms: Easily create dynamic online forms to capture and submit accurate and current data.
• Tina CMS: An open source toolkit for building front-end content-management into your website.
• Belajarpython Open source Indonesian python programming tutorial site.
• Uno Platform: Build Mobile, Desktop and WebAssembly apps with C# and XAML. Today. Open source and professionally supported.
• Jenkins X: Jenkins X provides pipeline automation, built-in GitOps, and preview environments to help teams collaborate and accelerate their software delivery at any scale.
• Changeloguru: Auto-generate changelog from conventional commits, written in Go.

хочете ваш проєкт в списку? надсилайте запит про додавання.