{"canonical_url":"https://engineer.company/uk/glossary/semantic-versioning/","content_markdown":"# Семантичне версіонування\n\n## Що це таке\n\nСемантичне версіонування, англійською semantic versioning або скорочено SemVer,\n— це набір правил нумерації релізів, за якими сам номер показує, яку зміну\nмістить реліз. Специфікація, нині у версії 2.0.0, яку первісно написав Tom\nPreston-Werner, використовує три числа у форматі MAJOR.MINOR.PATCH: мажорну,\nмінорну й патч-версію. Реліз, що ламає публічний API, збільшує мажорну версію;\nреліз, що додає функціональність, сумісну з попередньою версією, збільшує\nмінорну; реліз, що лише виправляє помилки й не зачіпає API, збільшує\nпатч-версію. Коли якесь число зростає, числа праворуч від нього скидаються до\nнуля, а порівнюють їх як числа, а не як текст, тож `1.10.0` іде після `1.9.0`.\n\nУсе тримається на одній вимозі: проєкт мусить оголосити публічний API, у коді чи\nв документації, бо номери описують зміни саме цього API і нічого більше.\nВипущену версію змінювати не можна; виправлення — це вже нова версія. Нульова\nмажорна версія, `0.y.z`, призначена для початкової розробки: будь-що може\nзмінитися будь-коли, і API не слід вважати стабільним. Версія `1.0.0` — це\nмомент, коли публічний API визначено, і відтоді номери стежать за тим, як він\nзмінюється.\n\nФормат доповнюють дві необов'язкові позначки. Передрелізну версію пишуть після\nдефіса, і вона стоїть перед релізом, до якого веде: `1.0.0-alpha` іде перед\n`1.0.0-alpha.1`, далі йдуть `1.0.0-beta`, `1.0.0-rc.1` і нарешті `1.0.0`.\nМетадані збірки пишуть після знака плюс, як у `1.0.0+20130313144700`, і під час\nупорядкування версій їх ігнорують, тож дві версії, що відрізняються лише ними,\nмають однаковий пріоритет. Літера v на початку, як у тегу Git `v1.2.3`, до\nсемантичної версії не належить; специфікація називає її поширеним способом\nпозначити номер версії. Go робить її обов'язковою: канонічна версія модуля Go —\nце літера v, за якою йде семантична версія.\n\n## Чому це важливо\n\nСпецифікація відштовхується від того, що вона називає пеклом залежностей. Якщо\nзадати залежності надто жорстко, виникає блокування версій: оновлення одного\nпакета вимагає нових версій усього, що від нього залежить. Якщо надто вільно,\nвиникає безлад у версіях: розраховують на сумісність із більшою кількістю\nмайбутніх версій, ніж розумно. Номер версії з узгодженим значенням дає проєкту\nзмогу сказати, що він прийме: бібліотека, якій потрібна функція, вперше додана у\n3.1.0, може приймати будь-що від 3.1.0 до 4.0.0, не включно, і отримувати\nпізніші виправлення та доповнення без жодної правки вимоги.\n\nМенеджери пакетів діють на підставі цієї обіцянки, нічого не питаючи. У Cargo,\nменеджері пакетів Rust, звичайна вимога на кшталт `\"1.2.3\"` — це caret-вимога,\nяка означає щонайменше 1.2.3, але нижче за 2.0.0. Записуючи `Cargo.lock`, Cargo\nбере найбільшу версію в цьому діапазоні й лишається на версіях 1.x і після\nпублікації 2.0.0, бо вважає 2.0.0 несумісною. У node-semver, що описує себе як\nзасіб семантичного версіонування для npm, `^1.2.3` означає `\u003e=1.2.3 \u003c2.0.0-0`, а\n`~1.2.3` дозволяє лише зміни рівня патча, `\u003e=1.2.3 \u003c1.3.0-0`. Go вбудовує\nправило у шляхи імпорту: починаючи з мажорної версії 2, шлях модуля мусить\nзакінчуватися суфіксом на зразок `/v2`, тож дві несумісні мажорні версії — це\nдва різні шляхи імпорту. Мінімальний вибір версій (minimal version selection) у\nGo бере для кожного модуля найвищу версію, якої вимагає будь-яка з вимог, і саме\nвона є мінімумом, що задовольняє їх усі. Результат не зберігається в lock-файлі;\nкожна команда, що працює з модулями, обчислює його заново.\n\nНіщо з цього не робить номер гарантією. Це обіцянка тих, хто публікує пакет, і\nвона варта рівно стільки, скільки їхнє судження про те, яку зміну вважати\nнесумісною. Саме тому Cargo публікує довгий посібник із сумісності, який\nрозкладає зміни на мажорні, мінорні та потенційно несумісні (possibly-breaking).\nЗдебільшого посібник говорить про зміни, через які код, що вчора компілювався,\nсьогодні не компілюється. Сам посібник зазначає, що майже будь-яка зміна несе\nпевний ризик для поведінки під час виконання і що питання, чи є така зміна\nнесумісною, мейнтейнери зазвичай вирішують на власний розсуд.\n\n## Як це виглядає на практиці\n\nПростежмо релізи вигаданої бібліотеки Rust під назвою tally. Версія 0.4.2 — ще\nпочаткова розробка. Версія 1.0.0 оголошує публічний API стабільним. Версія 1.0.1\nвиправляє помилку округлення й є патчем. Версія 1.1.0 додає функцію\n`parse_strict` і позначає стару `parse` як застарілу (deprecated): специфікація\nвимагає для цього мінорного релізу й просить випустити принаймні один такий\nреліз, перш ніж функцію видалять. Версія 2.0.0 видаляє `parse` і є мажорним\nрелізом. Версія 2.1.0-rc.1 — передрелізна версія наступної мінорної.\n\nЗастосунок, що залежить від tally і ще трьох вигаданих крейтів, записує свої\nвимоги в `Cargo.toml`. Коментарі показують діапазон, який Cargo вичитує з\nкожного рядка:\n\n```toml\n[dependencies]\ntally = \"1.0.1\"         # \u003e=1.0.1, \u003c2.0.0: takes 1.1.0, never 2.0.0\nledger = \"0.4.2\"        # \u003e=0.4.2, \u003c0.5.0: 0.5.0 counts as breaking\nstamp = \"~1.2.3\"        # \u003e=1.2.3, \u003c1.3.0: patch releases only\nquill = \"=2.1.0-rc.1\"   # exactly this pre-release\n```\n\nРядок `ledger` показує домовленість інструментів, а не специфікації: Cargo\nвважає сигналом несумісності крайнє ліве ненульове число, тоді як специфікація\nкаже, що до 1.0.0 будь-що може змінитися будь-коли. Передрелізні версії Cargo до\nвимоги не включає, якщо вона прямо не називає одну з них, тож вимога `\"2.0\"`\nніколи не підхопила б реліз-кандидат tally. Точна форма `=` в останньому рядку —\nсаме той випадок, коли, за документацією Cargo, повністю задана вимога може бути\nвиправданою: залежність від передрелізної версії без ризику несумісних змін між\nпередрелізами. Знайдені версії записуються в `Cargo.lock`, а `cargo update`\nпересуває їх у межах цих діапазонів. З параметром `--locked` збірка, якій\nдовелося б змінити lock-файл, натомість завершується помилкою.\n\nЧого номер не охоплює, то це всього, що лежить поза API.\n[Перевірка ліцензій 644 крейтів Rust](/uk/portfolio/know-the-licence-of-everything-you-ship/),\nзапроваджена у вересні 2026 року, під час кожної збірки звіряє ліцензію кожного\nкрейта зі списком умов, які приймає проєкт, бо рутинне оновлення версії глибоко\nв графі залежностей може непомітно змінити умови, на яких застосунок можна\nрозповсюджувати, у lock-файлі, який ніхто не читає рядок за рядком. Щоб довести,\nщо перевірка працює, її двічі навмисно змусили спрацювати. Перший раз\nліцензійний вираз крейта переписали: так виглядає ситуація, коли автори крейта\nзмінюють його умови між версіями, а рев'ю цього не помічає, бо сам крейт не\nновий. Другий раз закріплену ревізію ядра змінили без повторної генерації\nперевірки. Семантична версія може сказати, що 1.4.0 має працювати з кодом,\nнаписаним під 1.0.0. Але вона не скаже, чи вам досі можна її постачати.\n\n## Де виникають проблеми\n\n**Несумісна зміна в мінорному релізі.** Таке стається випадково або через інше\nрозуміння того, що вважати несумісним. Посібник Cargo перелічує зміни, які\nздаються нешкідливими, але такими не є: новий варіант у публічному enum ламає\nкод, що зіставляє його вичерпно, якщо enum від початку не позначили\n`#[non_exhaustive]`, а в рідкісних випадках із glob-імпортами навіть новий\nпублічний елемент спричиняє помилку компіляції. Відповідь специфікації, щойно\nпомилку помічено, — випустити нову мінорну версію, яка відновлює сумісність,\nніколи не змінювати вже опублікований реліз і повідомити користувачам, яка\nверсія порушила правила. На боці споживача таку помилку ловлять lock-файл,\nзбережений у репозиторії, і тести, що запускаються при кожному оновленні, ще до\nтого, як її помітять у продакшні.\n\n**Роки на 0.x.** За специфікацією нульова мажорна версія взагалі не має\nстабільного API. Її FAQ каже про це прямо: якщо програмне забезпечення вже\nпрацює в продакшні, йому, найімовірніше, вже час мати версію 1.0.0. Інструменти\nзаповнюють цю прогалину власною домовленістю: Cargo і node-semver вважають\nнесумісним крайнє ліве ненульове число, тож `^0.2.3` приймає лише наступні\nрелізи 0.2.x, а `^0.0.3` не приймає жодних оновлень. Бібліотека, що роками\nстоїть на 0.x, має користувачів, які від неї залежать, але не має перед ними\nжодної визначеної обіцянки. Випустіть 1.0.0, щойно на API почали покладатися: це\nзмінює номер, а не код.\n\n**Вичитувати з номера більше, ніж у ньому є.** Сумісність за специфікацією\nстосується публічного API. Посібник Cargo відносить підвищення мінімальної\nверсії Rust, потрібної крейту, до потенційно несумісних змін і загалом радить\nвважати його мінорною зміною, тож мінорне оновлення може зупинити збірку зі\nстарішим набором інструментів Rust. Поле `package.rust-version` дає змогу\nмеханізму розв'язання залежностей Cargo за потреби спробувати старіші версії\nкрейта. Умови ліцензії, продуктивність і поведінка, яку API ніколи не\nдокументував, лежать поза номером цілком. Перевіряйте їх окремо, перевіркою\nліцензій і тестами, а не виводьте з мінорного релізу.\n\n**Дві мажорні версії в одній збірці.** Коли двом залежностям потрібні несумісні\nверсії одного крейта, скажімо 0.6 і 0.7, Cargo збирає обидві. Компілятор вважає\nїхні типи різними, навіть коли назви збігаються. Зазвичай це закінчується\nпомилкою компіляції, а іноді проявляється лише під час виконання: документація\nCargo описує невдале приведення типу (downcast), коли об'єкт створила бібліотека\nз версією 1.0.0, а код, що її викликає, приводить його до типу з 2.0.0. Команда\n`cargo tree -d` показує дубльовані версії і те, звідки вони беруться. Автор\nбібліотеки може пом'якшити мажорний реліз прийомом, який документація Cargo\nназиває «semver trick»: опублікувати нову мажорну версію, а потім точковий реліз\nстарої, який реекспортує типи з нової.\n\n## Що почитати далі\n\n- [Semantic Versioning 2.0.0](https://semver.org/) — специфікація та її FAQ,\n  зокрема що робити, якщо несумісну зміну випустили помилково. Є й український\n  переклад.\n- [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html)\n  — посібник Cargo Book про те, які зміни в бібліотеці Rust є мажорними,\n  мінорними чи потенційно несумісними, кожна з прикладом.\n- [Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)\n  — синтаксис вимог Cargo: типові, caret-, tilde- і порівняльні вимоги та те, як\n  зіставляються передрелізні версії.\n- [Dependency Resolution](https://doc.rust-lang.org/cargo/reference/resolver.html)\n  — як Cargo обирає версії, що зберігає lock-файл і чим небезпечні дві несумісні\n  версії в одному графі.\n- [node-semver](https://github.com/npm/node-semver) — засіб семантичного\n  версіонування для npm із правилами діапазонів caret, tilde і передрелізних\n  версій.\n- [Go Modules Reference](https://go.dev/ref/mod) — суфікси мажорних версій,\n  правило сумісності імпорту та мінімальний вибір версій.\n\n\u003chttps://engineer.company/uk/glossary/semantic-versioning/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Що обіцяє MAJOR.MINOR.PATCH, як на нього спираються Cargo, npm і Go і чого номер версії сказати не може.","formats":{"gemtext":"https://engineer.company/uk/glossary/semantic-versioning/index.gmi","gopher":"https://engineer.company/uk/glossary/semantic-versioning/gophermap","html":"https://engineer.company/uk/glossary/semantic-versioning/","json":"https://engineer.company/uk/glossary/semantic-versioning/index.json","markdown":"https://engineer.company/uk/glossary/semantic-versioning/index.md","pdf":"https://engineer.company/uk/glossary/semantic-versioning/index.pdf"},"kind":"page","language":"uk","title":"Що таке семантичне версіонування?","url":"https://engineer.company/uk/glossary/semantic-versioning/","version":1}