Семантикалық нұсқалау

Семантикалық нұсқалау

1) SemVer дегеніміз не және ол не үшін қажет

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

Мақсаты: келісімшарттардың тұрақтылығы туралы уағдаласу және жаңартулардың құнын төмендету.

2) Нұсқа пішімі

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

`1. 4. 7 '- тұрақты релиз.
`1. 5. 0-rc. 2 '- алдын ала релиз (release candidate № 2).
`2. 0. 0+linux. arm64 '- build-метадеректер (нұсқаларды салыстыруға әсер етпейді).

1. Алдымен «MAJOR», содан кейін «MINOR», содан кейін «PATCH» салыстырылады.

2. Алдын ала релиздер тиісті тұрақты нұсқадан аз: '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) Алдын ала релиздер және арналық стратегиялар

• Белгілер: 'alpha', 'beta', 'rc'. Мысал: '2. 3. 0-beta. 3`.
• Арналар: nightly → alpha → beta → rc → stable.
• Саясат: Алдын ала релиздер әдепкі сынақ жинақтары үшін транзиттік тәуелділік ретінде түспеуі керек.

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 боттар) шығарылады.

7) API үшін нұсқалау саясаты

Ашық API: қатаң SemVer; breaking → MAJOR.
HTTP/REST: URL нұсқасы/тақырыбы: '/v1/... ', '/v2/...' немесе 'Accept: application/vnd. org. service. v2+json`.
JSON-схемалар: шағын кеңейту - жаңа міндетті емес өрістер; major - міндетті жою/өзгерту.
gRPC/Protobuf: жаңа нөмірлері бар жаңа өрістерді қосыңыз; өріс нөмірлерін қайта пайдаланбаңыз; бұрынғыларды «сындыру» емес, → deprecate жою.

8) Деректер мен көші-қон схемалары

ДҚ көші-қоны 'app @ 1' бағдарламасының нұсқаларымен үндестіріледі. 8. 0 'талап етеді' schema @ 1. 8. x`.
Схеманы өзгерту үшін - фазалар: expand (қосу), migrate, contract (жою). Нұсқаны тек ескі келісімшартты жойғанда ғана MAJOR-ға дейін көтеріңіз.
Көшіру кезінде екі рет жазуды/оқуды қолдаңыз.

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

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

• Independent versions (Lerna/Changesets) - оқшаулауды күшейтеді.
• Lock-step - оңай коммуникация, бірақ жалған MAJOR-дар көп.
• Микросервистер үшін келісімшарттарды (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 күн).
Бақылау: user/tenant-контексті бар ескірген эндпоинттерді пайдалануды логикалаңыз.
Жою: келесі 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-ды арттыру («маркетингтік нұсқалар»).
'PATCH' деген бүркемеленген breaking-өзгерістер.
Прод-қосымшалардың транзиттік тәуелділігіндегі алдын ала релиздер.
Жаңа тегсіз артефактіні өзгерту (мутабельді нұсқалар).
ДБ коды мен схемасының келісілмеген нұсқалары.

14) Енгізу чек-парағы (0-45 күн)

0-10 күн

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

11-25 күн

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

26-45 күн

deprecation policy және ескірген API телеметриясын енгізіңіз.
Келісімшарттар (OpenAPI/Proto) мен сервистердің нұсқаларын синхрондаңыз.
«latest» және саясат деңгейіндегі үйлесімді тегтерге (ОРА/CI регламенттері) тыйым салыңыз.

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

Тек SemVer тегімен шығарылатын артефактілер%.
MINOR нұсқалары арасындағы орташа көші-қон уақыты.
Жасырын breaking-өзгерістерге байланысты оқиғалар саны.
Репозиторийлердегі Conventional Commits жабыны (> 95%).
Өнімдегі қалқымалы диапазонсыз тәуелділіктің үлесі (> 90%).

16) SemVer қажет емес кезде

Сыртқы тұтынушыларсыз ішкі жылдам прототиптер (мерзімі көрсетілген нұсқалау).
Эксперименттік фичтері бар деректер/модельдер (конвертерлер деңгейінде үйлесімділігі бар жақсы Model/Schema Versioning).
Тұрақты көпшілік API жоқ контент-пакеттер.

17) Қорытынды

SemVer - өндіруші мен тұтынушы арасындағы сенім келісімшарты. Үйлесімділікті бұзатын нәрсені нақты анықтаңыз, релиздер түрлерін тануды және артефактілерді жариялауды автоматтандырыңыз, мөлдір CHANGELOG жүргізіңіз және депривация саясатын сақтаңыз. Сонда жаңартулар дағдылы, болжамды және қауіпсіз болады - ал инфрақұрылым мен API бизнес үшін күйзеліссіз дамитын болады.