نسخهبندی معنایی

Semantic Versioning (SemVer) - یک قرارداد در مورد اینکه چگونه شماره نسخه نشان دهنده ماهیت تغییرات است. فرمت: بزرگ جزئی است. پچ [-PRERELEASE] [+ ساخت].

• MAJOR - تغییرات ناسازگار (شکستن).
• MINOR - ویژگی های متقابل سازگار/پسوند.
• PATCH - رفع اشکال/امنیت سازگار با عقب.

هدف: تکامل قابل پیش بینی API ها، رویدادها، طرح داده ها، SDK ها و پیکربندی ها بدون خرابی ناگهانی مصرف کننده.

1) شماره های قرارداد

X.Y.Z[-alpha.1    -rc.1][+build.sha]

پیش انتشار ('alpha'، '-beta'، '-rc') - مجامع ناپایدار ؛ قول هماهنگی ندهید.
ساختن فراداده ('+ sha') - بر ترتیب مقایسه تأثیر نمی گذارد، برای ردیابی مفید است.
تا 1. 0. 0 هر تغییری را می توان شکستن در نظر گرفت (اما بهتر است از ابتدا قوانین را دنبال کنید).

2) چه چیزی را در نظر بگیرید شکستن/جزئی/پچ

• رفع اشکالات و امنیت بدون تغییر قرارداد.
• به روز رسانی docking که قرارداد را تحت تاثیر قرار نمی.
• بهینه سازی بدون تغییر پاسخ/حوادث/طرح.

• فیلدها/متدها/نقاط پایانی اختیاری جدید اضافه کنید.
• گسترش ارزش های enum اگر مصرف کنندگان ارزش های نا آشنا را تحمل کنند.
• شاخص های جدید پایگاه داده، ستون های nullable با پیش فرض، رویدادهای جدید علاوه بر موارد قدیمی.

• حذف/تغییر نام زمینه, تغییر انواع, اجباری.
• تغییر معناشناسی/وضعیت/کد خطا.
• تغییر قالب سریال، طرح کلیدی، پروتکل حمل و نقل.
• فشرده سازی/ادغام موضوعات، انتقال معنای رویداد، تغییر طرح پارتیشن بندی.
• مهاجرت پایگاه داده که نیاز به «دو فاز» سوئیچینگ بدون سازگاری به عقب.

3) نسخه سازی مصنوعی

3. 1 استراحت

انواع: 'URI/v1/...'، هدر ('Accept: application/vnd. ACME. بازی + JSON ؛ version = 1 '), پارامتر.
توصیه: نسخه در URI برای API های عمومی ؛ برای داخلی - از طریق مذاکره هدر c.
MINOR: فیلدهای اختیاری، فیلترها/منابع جدید را اضافه کنید. پاسخ های فعلی را تغییر ندهید.
PATCH: رفع، اصلاح تعریف، مرتب سازی پایدار.

3. 2 گرم کامپیوتر

تغییر MAJOR → امضا/نوع (بسته جدید/خدمات: 'acme. کیف پول v2 ').
زمینه های جدید - برچسب اختیاری ؛ کاربر باید ناشناخته ها را نادیده بگیرد.
ما فیلدها را حذف نمی کنیم: «depricket + reserve a number»، حذف - فقط در MAJOR بعدی.

3. 3 GraphQL

جزئی: زمینه های جدید/انواع/پرس و جو ؛ حذف - از طریق پنجره مهاجرت «مستهلک شده»، حذف کامل - MAJOR.
تغییر nullable → non-nullable - MAJOR.

3. 4 رویدادها و موضوعات (کافکا/SQS)

طرحواره در طرحواره رجیستری: تکامل افزودنی (اضافه کردن زمینه با پیش فرض).
نسخه ناسازگار جدید → موضوع/موضوع جدید ("بهتر است. حل و فصل. v2 ').
کلید پارتیشن بندی در MAJOR تغییر ناپذیر است.

3. دیاگرام های 5 DB

1. اضافه کردن یک ستون (nullable/default) →

2. پر کردن در backfill

3. ترجمه → خواندن

4. قدیمی (فقط MAJOR) را حذف کنید.

تغییر نوع/PK/منحصر به فرد - MAJOR، تحت phicheflag و ورود دوگانه.

3. 6 SDK/CLI

روش ها/امضاهای عمومی همان قوانین هستند.
برای تولید خودکار (OpenAPI/Proto) - نسخه ای از نام دسته ای و مصنوعات.

4) سیاست محرومیت و چرخه زندگی

هر تغییر شکستن قبل از تخریب (معمولا 90-180 روز برای خارجی، 30-60 برای داخلی) است.
ارتباطات: changelog، ایمیل/webhooks به شرکای، آگهی ها در پورتال توسعه دهنده.
حالت دوگانه: نگه داشتن «v1» و «v2» به صورت موازی، نظارت بر سهم ترافیک «v1».

هدر غروب آفتاب (REST): 'غروب خورشید: 2026-03-31'، 'لینک: ؛ rel = «کاهش ارزش»

5) مذاکره نسخه

مشتری نسخه مورد نظر + حداکثر نسخه پشتیبانی شده را ارسال می کند (به عنوان مثال، «Accept-Version: 1,2»).
سرور با «Content-Version: 2» پاسخ می دهد.
در پروتکل های دو طرفه (WebSocket، gRPC) - تبادل فریم های Hello با «supported _ versions».

6) ارائه دهنده آداپتور ادغام (ACL)

ارائه دهنده خارجی طرح را تغییر می دهد - در داخل آداپتور ما نقشه های v1/v2 را نگه می داریم و MINOR را برای رویداد داخلی آزاد می کنیم، قرارداد دامنه ما را حفظ می کنیم.
اگر تغییرات خارجی راه خود را در داخل ایجاد کنند، این مهمترین رویداد دامنه ما و یک موضوع جدید است.

7) تغییر برچسب ها و برچسب ها

• «ترس:»... → جزئی
• عکس:... '/' chore ',' docs ',' perf '(بدون قرارداد) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' یا 'BREAKING CHANGE:' در MAJOR → بدن

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) اتوماسیون را آزاد کنید

CI: اعتبار سنج مدار (OpenAPI/Protobuf/Avro/JSON-Schema)، تشخیص شکستن انتشار. بیشتر

SemVer-bot: تجزیه و تحلیل کمیته های متعارف → محاسبه ضربه (عمده/جزئی/پچ)، قرار می دهد یک برچسب، تولید changelog.
CD: استقرار و انتشار جداگانه (phicheflags/configs فعال کردن نسخه جدید).
کنترل: «آخرین» را در PRO منتشر نکنید تا قناری موفق و SLO های توافق شده.

9) معناشناسی برای تنظیمات و سیاست ها

Configs (YAML/JSON) همچنین یک نسخه طرح دارد: «schema _ version: 3».
MINOR - زمینه های اختیاری جدید/قوانین MAJOR - تغییر ساختار/تعهد.
پشتیبانی v2/v3 در اعتبار سنج ؛ config migrator with ناسازگاری گزارش.

10) تست سازگاری

تست قرارداد مبتنی بر مصرف کننده (Pact): در هر ادغام.
تست تکامل طرح: بارهای قدیمی را بر روی یک طرح جدید اجرا کنید و بالعکس.
Replay - ترافیک تولید «v1» را به «v2» در سایه پخش می کند.
Property-based: مقاومت در برابر زمینه های نا آشنا/enum.

11) مشاهده توسط نسخه

معیارهای برچسب/سیاهههای مربوط: 'api _ version'، 'schema _ version'، 'event _ version'.
داشبورد مهاجرت: سهم ترافیک توسط نسخه ها، خطا/تاخیر توسط 'v1/v2'.
هشدارها: اگر «v1» طبق برنامه پیش نرود ؛ رشد 4xx/5xx پس از انتشار v2.

12) الگوهای مهاجرت بدون خرابی

گسترش → مهاجرت → قرارداد (БД).
نوشتن دوگانه + مقایسه واگرایی قبل از تعویض خواندن.
مقایسه سایه برای رتبه بندی/قوانین.
قناری توسط مستاجر/منطقه ؛ پرچم های ویژه برای بازگشت سریع.
Read-compat/Write-compat windows: نسخه جدید داده های قدیمی را می خواند، اما در قالب جدیدی می نویسد.

13) ضد الگوهای

«نسخه در هر فیلد» به جای نسخه منبع/رویداد.
تغییرات شکستن پنهان تحت MINOR (به عنوان مثال، تغییر پیش فرض).
حذف معیارهای تخریب شده بدون پنجره و مصرف.
«برای همیشه v1»: هیچ برنامه ای برای حذف نسخه های قدیمی → بدهی های فنی و آسیب پذیری.
نسخه کسب و کار و نسخه تصویر کانتینر را مخلوط کنید.

14) چک لیست سیاست نسخه

• فرمت نسخه ثابت و منابع حقیقت (رجیستری/پورتال).
• لیست تایید شده از معیارهای شکستن توسط مصنوعات (REST/gRPC/GraphQL/events/DB).
• فرآیند نمایندگی: زمان بندی، ارتباطات، غروب آفتاب/آگهی ها، دو اجرا شود.
• چک کننده دیفرانسیل اتوماتیک و کمیته های متعارف.
• نسخه و داشبورد مصرف هشدار.
• مهاجرت playbooks (گسترش/مهاجرت/قرارداد, دو نوشتن, سایه).
• پیکربندی ها و SDK ها نسخه ها و پرونده های خاص خود را دارند.
• مستندات «نحوه انتخاب یک نسخه» برای مشتریان و «نحوه ارتقاء» برای تیم ها.

15) نمونه هایی از نسخه (موارد iGaming)

'BetSettled v1' event → 'v2': اضافه شده 'void _ reason' (اختیاری) و 'مالیات. مقدار '(اختیاری) - جزئی. تغییر نام «پرداخت» → «win _ amount» - MAJOR، یک موضوع جدید.
REST "/کیف پول/انتقال ": فیلتر اضافه شده" ؟ tenant _ id = - جزئی. کد خطای تغییر یافته «409» → «422» - MAJOR.
GraphQL: علامت گذاری شده "پخش کننده. age به عنوان «@ deprecated» به نفع «بازیکن». گروه سنی - انتشار در MINOR، حذف در MAJOR پس از دوره X.
DB: ستون 'bonus _ wager _ left' nullable - MINOR اضافه شده است. ساخته شده غیر صفر و حذف 'پاداش _ چپ' - MAJOR (از طریق گسترش/قرارداد).

نتیجه گیری

نسخه سازی معنایی در مورد اعداد نیست، بلکه در مورد اعتماد و پیش بینی است. قوانین روشن، چک خودکار، deprictions کنترل شده، و تله متری شفاف اجازه می دهد API ها، حوادث، و طرح های بدون درد به تکامل برای ادغام - و انتشار تغییرات اغلب، با خیال راحت، و معنادار.