Семантикалык версиялоо

Семантикалык чыгаруу

1) Эмне SemVer жана эмне үчүн керек

• MAJOR - шайкеш келбеген өзгөрүүлөр (breaking changes).
• MINOR - API менен шайкеш келген жаңы функционалдык.
• PATCH - кайтарылма ылайыктуу кемчиликтерди оңдоо.

Максаты: келишимдердин туруктуулугу жөнүндө макулдашуу жана жаңыртуулардын баасын төмөндөтүү.

2) Версия формат

• `MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7 '- туруктуу чыгаруу.
`1. 5. 0-rc. 2 '- pre-релиз (release candidate № 2).
`2. 0. 0+linux. arm64 '- build-метадеректер (версияларды салыштырууга таасир этпейт).

1. Адегенде "MAJOR", андан кийин "MINOR", андан кийин "PATCH" салыштырылат.

2. Pre-релиздер тиешелүү туруктуу чыгаруу аз: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Build-метадеректер ('...') тартипке таасир этпейт: '1. 2. 0+001 == 1. 2. 0`.

3) Эмне breaking change болуп эсептелет

• Коомдук ыкмалар/эндпоинттердин белгисин алып салуу/атын өзгөртүү/өзгөртүү.
• Кирүү/чыгуу форматын өзгөртүү (JSON схемасы, түрлөрү).
• Ката келишимдерин өзгөртүү (коддор/структуралар).
• side-effects/SLAs өзгөртүү (мисалы, катуу чектер же жаңы милдеттүү талаалар).

Эмес breaking (туура ишке ашырууда): кошумча талааларды кошуу, жаңы баалуулуктар менен enum кеңейтүү (эгерде кардар аларды этибарга албаса), жаңы эндпоинттер, учурдагы чакырыктарга таасир этпеген дефолттор менен жаңы желектер.

4) Pre-релиздер жана каналдык стратегиялар

• Tags: 'alpha', 'beta', 'rc'. Мисал: '2. 3. 0-beta. 3`.
• Каналдар: nightly → alpha → beta → rc → stable.
• Саясат: Pre-релиздер демейки өндүрүштүк чогултуу үчүн транзиттик көз карандылык катары түшпөшү керек.

5) Версия диапазондору жана көз карандылык тактыгы

5. 1 Node/npm (SemVer демейки)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(MINOR/PATCH уруксат берет, MAJOR бекитет).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(MINOR ичинде PATCH жол).
`1. 4. x '- 1 ар кандай жамоо. 4.
Так пин: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- так чек аралар.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- кошо алганда/гана.
Прод-критикалык экспонаттар үчүн катуу тепкилөө сунушталат.

5. 4 Go modules

Ар дайым толук теги 'vMAJOR. MINOR. PATCH ';' v2 + 'модулунун суффиксин талап кылат '/v2'.

Сунуш: тиркемелер үчүн - так пиндер (reproducible builds). Китепканалар үчүн - caret диапазондору (жаңылоону сынбастан жеңилдетүү).

6) CHANGELOG и Conventional Commits

Структураланган өзгөртүү журналы ачык-айкындуулукту жогорулатат.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
Кыйытма белгиси же блок 'BREAKING CHANGE' MAJOR жогорулатуу жарыялайт.
CHANGELOG коммиттердин тарыхынан (release-notes bots) пайда болот.

7) API үчүн чыгаруу саясаты

Коомдук API: катуу SemVer; breaking → MAJOR.
HTTP/REST: URL версиясы/аталышы: '/v1/... ', '/v2/...' же 'Accept: application/vnd. org. service. v2+json`.
JSON схемалар: майда кеңейтүү - жаңы кошумча талаалар; major - милдеттүү түрдө алып салуу/өзгөртүү.
gRPC/Protobuf: жаңы сандар менен жаңы талааларды кошуу; талаа номурларын кайра колдонбоңуз; жок → deprecate, эмес, "сындырып" бар.

8) Маалыматтар жана миграция схемалары

DD миграциялары тиркеменин версиялары менен синхрондоштурулат: 'app @ 1. 8. 0 'талап' schema @ 1. 8. x`.
Схеманы өзгөртүү үчүн - фазалар: expand (кошуу), migrate, contract (алып салуу). Эски келишимди алып салганда гана MAJOR версиясын көтөрүңүз.
Миграция учурунда кош жазууну/окууну колдоо.

9) Монорепо жана микросервис

Multi-package: ар бир пакети өзүнүн 'MAJOR. MINOR. PATCH`; мета-артефакттар үчүн гана жалпы тамыр релиздер цикли.

• Independent versions (Lerna/Changesets) - изоляцияны күчөтөт.
• Lock-кадам - жөнөкөй байланыш, бирок көбүрөөк жалган MAJORs.
• Микросервистер үчүн контракттарды (OpenAPI/Protobuf) өзүнчө версия менен бекитиңиз: 'contract @ 2. 1. 0 ', кызмат ага ылайык келет.

10) CI/CD релиздерди автоматташтыруу

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

CHANGELOG генерациясы, релиз-ноут жарыялоо, GitOps-репо көз карандылыкты жаңыртуу, 'main' дайыма акыркы туруктуу тегин көрсөтүп турат.

11) Депривация саясаты (deprecation policy)

кулактандыруу: MINOR-релизинде deprecated катары белгилөө, EOL мөөнөтү (мисалы, 90 күн).
Байкоо: колдонуучу/tenant контекстинде эскирген End Points колдонуу Логин.
Алып салуу: кийинки MAJOR. Миграция жолун документтештириңиз.

12) мисалдар жана үлгүлөр

12. 1 SemVer валидациясынын үзгүлтүксүз билдирүүсү

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 салыштыруу мисалдар

`1. 2. 3` < `1. 10. 0 '(MINOR салыштыруу).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Көз карандылык саясаты (YAML мисалы)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Анти-үлгүлөрү

'latest '/сүзүүчү тегтерди прод.
Чыныгы сыныктары жок MAJOR жогорулатуу ("маркетинг нускалары").
Жашыруун breaking-өзгөрүүлөр 'PATCH' деген ат менен.
Pre-релиздер өткөөл көз карандылыкта прод-тиркемелер.
Жаңы тегсиз артефактты өзгөртүү (мутабель версиялары).
Коддун жана БД схемасынын макулдашылбаган версиялары.

14) киргизүү чек-тизмеси (0-45 күн)

0-10 күн

SemVer милдеттүү стандарт катары кабыл алуу, сынык критерийлерин бекитүү.
Conventional Commits жана 'BREAKING CHANGE' талаасы менен PR үлгүсүн киргизүү.

11-25 күн

semantic-release/changesets, автогенерация CHANGELOG туташтыруу.
Кол коюу жана артефакттарды vX теги боюнча жарыялоону тууралаңыз. Y.Z`.

26-45 күн

Эски APIлерди колдонуу үчүн deprecation policy жана телеметрия киргизиңиз.
Контракттардын (OpenAPI/Proto) жана кызматтардын версияларын синхрондоштуруу.
Тыюу 'latest' жана саясат деъгээлинде мутабель теги (ORA/CI регламенттери).

15) Жетилүү метрикасы

SemVer тегинде гана чыгарылган экспонаттардын%.
MINOR версияларынын ортосундагы орточо миграция убактысы.
улам жашыруун breaking-өзгөрүүлөр менен окуялар саны.
Кампа Conventional Commits (> 95%).
сууда сүзүүчү диапазондору жок көз карандылыктын үлүшү (> 90%).

16) Качан SemVer кереги жок

Тышкы керектөөчүлөрдүн жок ички тез прототиптери (даталанган чыгаруу ылайыктуу).
Маалыматтар/эксперименталдык сүрөттөр менен моделдер (мыкты конвертер деъгээлинде шайкештиги менен Model/Schema Versioning).
туруктуу коомдук API жок мазмун пакеттери.

17) Корутунду

SemVer - өндүрүүчү менен керектөөчүнүн ортосундагы ишеним келишими. Шайкештикти бузган нерсени так аныктаңыз, релиздердин түрлөрүн таанууну жана артефакттарды жарыялоону автоматташтырыңыз, ачык-айкын CHANGELOG жүргүзүңүз жана депривация саясатын сактаңыз. Ошондо жаңыртуулар күнүмдүк, болжолдонгон жана коопсуз болот - ал эми инфраструктура жана API бизнес үчүн шок жок өнүгөт.