Версияи семантикӣ

Тарҷумаи семантикӣ

1) Semver чист ва чаро он лозим аст

• MAJOR - тағиротҳои шикаста.
• MINOR хусусияти нави мувофиқ ба API мебошад.
• PATCH - ислоҳи камбудиҳои баръакс.

Мақсад: мувофиқа оид ба устувории шартномаҳо ва кам кардани арзиши такмилдиҳӣ.

2) Формати версия

• 'МАЙОР. МИНОР. ПАТЧ [-PRERELEASE] [+ BUILD] '

`1. 4. 7 'нашри устувор аст.
`1. 5. 0-rc. 2 '- пеш аз озодӣ (номзади озод № 2).
`2. 0. 0 + linux. arm64 '- сохтани метамаълумот (ба муқоисаи версия таъсир нарасонед).

1. Аввалан, 'MAJOR' муқоиса карда мешавад, баъд 'MINOR', баъд 'PATCH'.

2. Нашри пешакӣ аз версияи устувори мувофиқ хурдтар аст: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Сохтани метамаълумот ('+...') ба тартиби: '1 таъсир намерасонад. 2. 0+001 == 1. 2. 0`.

3) Чӣ тағиротро вайрон мекунад

• Нест кардан/тағйири ном/тағйири имзои усулҳои ҷамъиятӣ/нуқтаҳои ниҳоӣ.
• Тағйир додани формати вуруд/баромад (схемаи JSON, намудҳо).
• Тағйир додани шартномаҳои хато (кодҳо/сохторҳо).
• Таъсири иловагиро/SLA-ҳоро тағир диҳед (масалан, маҳдудиятҳои қатъӣ ё майдонҳои нави зарурӣ).

Вайрон накардан (агар дуруст иҷро карда шавад): илова кардани майдонҳои ихтиёрӣ, васеъ кардани энум бо арзишҳои нав (агар муштарӣ онҳоро нодида гирад), нуқтаҳои нав, парчамҳои нав бо пешфарз, ки ба зангҳои ҷорӣ таъсир намерасонанд.

4) Нашри пешакӣ ва стратегияҳои канал

• Барчаспҳо: 'алфа', 'бета', 'rc'. Мисол: '2. 3. 0-бета. 3`.
• Каналҳо: шабона → алфа → бета → rc → устувор.
• Сиёсат: Варақаҳои пешакӣ набояд ҳамчун вобастагии гузаранда барои маҷмӯаҳои пешфарз истеҳсол шаванд.

5) Диапазон ва дақиқии маҳдудият

5. 1 гиреҳ/нм (пешфарз Semver)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(имкон медиҳад MINOR/PATCH, MAJOR-ро ислоҳ кунад).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(имкон медиҳад PATCH дар доираи MINOR).
`1. 4. x 'ягон ямоқи дар 1 аст. 4.
PIN-и дақиқ: '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 Модулҳои равед

Ҳамеша барчаспҳои 'VMAJOR' -ро пур кунед. МИНОР. PATCH ';' v2 + 'суффикси модули '/v2' -ро талаб мекунад.

Тавсия: барои барномаҳо - пинҳои дақиқ (сохти такроршаванда). Барои китобхонаҳо - диапазонҳои карет (навсозиро бидуни танаффус осон мекунанд).

6) CHANGELOG i Ӯҳдадориҳои анъанавӣ

Сабти сохтори тағирот шаффофиятро беҳтар мекунад.

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' i t. д.
Нуқтаи илоҳӣ ё 'CHANGE CHANGE' як MAJOR эълон мекунад.
CHANGELOG аз таърихи супоришҳо ба вуҷуд омадааст (қайдҳо бо ботҳо).

7) Сиёсати версия барои API

API-ҳои ҷамъиятӣ: СЕМИ-и қатъӣ; шикастан → MAJOR.
HTTP/REST: версия бо URL/сарлавҳа: '/v1/... ', '/v2/...' ё 'Қабул: ариза/внд. org. хизматрасонӣ. v2 + json '.
Схемаҳои JSON: васеъшавии хурд - майдонҳои нави ихтиёрӣ; асосӣ - нест кардан/иваз кардан ҳатмӣ.
GRPC/Protobuf: майдонҳои навро бо рақамҳои нав илова кунед; Рақамҳои саҳроиро, ки беқурбшавиро нест мекунанд, аз нав истифода набаред.

8) Схемаҳои маълумот ва муҳоҷират

Муҳоҷирати пойгоҳи додаҳо бо версияҳои app @ 1 ҳамоҳанг карда шудааст. 8. 0 'талаб мекунад' schema @ 1. 8. х '.
Барои вайрон кардани тағироти схема - марҳилаҳо: васеъ кардан (илова кардан), муҳоҷират кардан, шартнома (нест кардан). Навсозӣ ба MAJOR танҳо вақте ки шумо шартномаи кӯҳнаро нест мекунед.
Дар тӯли муҳоҷират дучанд навиштан/хонданро дастгирӣ кунед.

9) Монорепос ва microservices

Бисёр бастаҳо: ҳар як баста дорои 'MAJOR. МИНОР. ПАТЧ '; сикли умумии решаи танҳо барои артефактҳои мета.

• Версияҳои мустақил (Lerna/Changesets) - ҷудокуниро зиёд мекунад.
• Қулфи қадам - муоширати осонтар, аммо MAJORS бардурӯғ.
• Барои microservices, шартномаҳоро ислоҳ кунед (OpEN API/Protobuf) бо нусхаи алоҳида: 'шартнома @ 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, санҷидани он, ки "асосӣ" ҳамеша ба теги охирини устувор ишора мекунад.

11) Сиёсати маҳрумшавӣ

Эълон: функсияи тамғагузорӣ, ки дар нашри MINOR фарсуда шудааст, мӯҳлати EOL (масалан, 90 рӯз).
Мушоҳида: Сабти истифодаи нуқтаҳои меросӣ бо контексти корбар/иҷорагир.
Нест кардан: дар MAJOR зерин. Роҳи муҳоҷиратро ҳуҷҷатгузорӣ кунед.

12) Намунаҳо ва қолабҳо

12. 1 Ифодаи санҷиши мунтазами Sem

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 + сохтан. 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) Анти-намунаҳо

Истифодаи барчаспҳои 'охирин '/шинокунанда дар prod.
Такмили MAJOR бидуни тақсимоти воқеӣ ("версияҳои маркетингӣ").
Тағироти шикастани пинҳонӣ зери ниқоби 'PATCH'.
Варақаҳои пешакӣ дар вобастагии гузариши барномаҳои истеҳсолӣ.
Артефактро бе теги нав иваз кунед (нусхаҳои қобили қабул).
Версияҳои номувофиқ ва схемаҳои пойгоҳи додаҳо.

14) Рӯйхати санҷиши амалисозӣ (0-45 рӯз)

0-10 рӯз

Semver-ро ҳамчун стандарти ҳатмӣ қабул кунед, меъёрҳои шикастаро тасдиқ кунед.
Ба ӯҳдадориҳои анъанавӣ ва қолаби PR бо майдони 'BREAKING CHANGE' дохил кунед.

11-25 рӯз

Пайваст кардани семантикӣ-озодкунӣ/тағирот, автогенератсияи CHANGELOG.
Батанзимдарории имзо ва нашри артефактҳо бар зидди барчасп. Й.З '.

26-45 рӯз

Сиёсати амортизатсия ва телеметрияро барои истифодаи мероси API ворид кунед.
Ҳамоҳанг кардани версияҳои шартномавӣ (OpEN API/Proto) ва хидматҳо.
Барчаспҳои "охирин" ва мувофиқро дар сатҳи сиёсат манъ кунед (қоидаҳои OPA/CI).

15) Нишондиҳандаҳои камолот

% артефактҳо, ки танҳо теги Semver нашр кардаанд.
Вақти миёнаи муҳоҷират байни версияҳои MINOR.
Шумораи ҳодисаҳо бо сабаби тағироти пинҳонии пинҳонӣ.
Фарогирии ӯҳдадориҳои анъанавӣ дар анборҳо (> 95%).
Таносуби вобастагӣ бидуни диапазони шиновар дар маҳсулот (> 90%).

16) Вақте ки Semver лозим нест

Прототипҳои дохилии рӯза бидуни истеъмолкунандагони беруна (версияи санаи мувофиқ мувофиқ аст).
Маълумот/моделҳо бо хусусиятҳои таҷрибавӣ (Модел/Схемаи беҳтар бо мутобиқат дар сатҳи конвертер).
Бастаҳои мундариҷа бидуни API ҷамъиятии устувор.

17) Хулоса

Sem-Ver шартномаи эътимод байни истеҳсолкунанда ва истеъмолкунанда мебошад. Ба таври возеҳ муайян кунед, ки чӣ мувофиқатро вайрон мекунад, шинохти навъи озодкунӣ ва нашри артефактро автоматӣ мекунад, CHANGELOG шаффофро нигоҳ медорад ва ба сиёсати маҳрумият аз озодӣ мувофиқат мекунад. Он гоҳ навсозиҳо муқаррарӣ, пешгӯишаванда ва бехатар хоҳанд буд - ва инфрасохтор ва API-ҳо бидуни такон ба тиҷорат рушд хоҳанд кард.