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

1) SemVer چیست و چرا لازم است

SemVer قوانین قابل پیش بینی برای اختصاص نسخه ها به مصنوعات (کتابخانه ها، API ها، خدمات، طرح ها) را تنظیم می کند تا مصرف کنندگان بدانند چه چیزی از به روز رسانی انتظار می رود:

MAJOR - شکستن تغییرات.
MINOR یک ویژگی جدید سازگار با API است.
PATCH - رفع نقص برگشت پذیر.

هدف: توافق در مورد ثبات قراردادها و کاهش هزینه های ارتقاء.

2) فرمت نسخه

فرمت پایه:

سرگرد. جزئی است. پچ [-PRERELEASE] [+ ساخت] '

`1. 4. 7 "انتشار پایدار است.
`1. 5. 0-RC 2 '- قبل از انتشار (نامزد انتشار شماره 2).
`2. 0. 0 + لینوکس 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 (به عنوان مثال، محدودیت های سخت و یا زمینه های مورد نیاز جدید).

شکستن نیست (اگر به درستی اجرا): اضافه کردن زمینه های اختیاری، گسترش enum با ارزش های جدید (اگر مشتری آنها را نادیده می گیرد)، نقاط پایانی جدید، پرچم های جدید با پیش فرض که تماس های فعلی تاثیر نمی گذارد.

4) پیش انتشار و استراتژی های کانال

پیش از انتشار به شما اجازه می دهد بدون شکستن وعده های SemVer تست کنید:

برچسب ها: «آلفا»، «بتا»، «rc». مثال: "2. 3. 0 بتا. 3`.
کانال های: شبانه → آلفا → بتا → rc → پایدار.
سیاست: پیش از انتشار نباید به عنوان وابستگی گذرا برای مجامع تولید پیش فرض سقوط کند.

5) محدوده نسخه و دقت محدودیت

اکوسیستم های واقعی از عبارات محدوده استفاده می کنند:

5. 1 گره/npm (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.
پین دقیق: '1. 4. 2`.

5. 2 پایتون (PEP 440، پیپ)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 "- مرزهای صریح.

5. 3 MAVEN/GRADLE (جاوا)

`[1. 4,2. 0) '- شامل/منحصر به فرد.
لگد زدن سخت برای مصنوعات حساس به مواد غذایی توصیه می شود.

5. 4 برو ماژول ها

همیشه برچسبهای «vMAJOR» را کامل کنید. جزئی است. PATCH '؛' v2 + 'نیاز به پسوند ماژول '/v2' دارد.

توصیه: برای برنامه های کاربردی - پین دقیق (ساخت تجدید پذیر). برای کتابخانه ها - محدوده مراقبت (تسهیل به روز رسانی بدون شکستن).

6) تغییر и کمیته های متعارف

تغییرات ساختاری شفافیت را بهبود می بخشد.

کمیته های متعارف:


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 از تاریخچه کامیتها (یادداشتهای انتشار توسط رباتها) ایجاد میشود.

7) سیاست نسخه برای API

API های عمومی: SemVer سخت ؛ شکستن بزرگ.

HTTP/REST: نسخه بندی توسط URL/هدر: '/v1/... ', '/v2/...' یا 'Accept: application/vnd. ORG. خدمات. V2 + JSON '

طرح های JSON: پسوند جزئی - زمینه های اختیاری جدید ؛ major - حذف/تغییر اجباری است.
gRPC/Protobuf: اضافه کردن زمینه های جدید با شماره های جدید ؛ استفاده مجدد از شماره های فیلد حذف استهلاک →، شکستن موجود نیست.

8) داده ها و طرح های مهاجرت

مهاجرت پایگاه داده با نسخه های app @ 1 هماهنگ شده است. 8. 0 'requires' schema @ 1. 8. X '.
برای شکستن تغییرات طرح - مراحل: گسترش (اضافه کردن)، مهاجرت، قرارداد (حذف). ارتقا به MAJOR تنها زمانی که شما قرارداد قدیمی را حذف کنید.
پشتیبانی دو نوشتن/خواندن برای مدت زمان مهاجرت.

9) Monorepos و خدمات میکرو

چند بسته: هر بسته دارای MAJOR خاص خود است. جزئی است. پچ ؛ چرخه انتشار ریشه مشترک فقط برای مصنوعات متا.

استراتژی های مختلف:

نسخه های مستقل (Lerna/Changesets) - انزوا را افزایش می دهد.
قفل گام - ارتباط آسان تر، اما بیشتر MAJORS کاذب.
برای میکروسرویسها، قراردادها (OpenAPI/Protobuf) را با یک نسخه جداگانه اصلاح کنید: "contract @ 2. 1. 0 "، سرویس آن را دنبال می کند.

10) اتوماسیون انتشار در CI/CD

محاسبه خودکار نسخه بر اساس کمیته های متعارف:

'fix' → 'PATCH', 'feat' → 'MINOR', '! '/' BREAKING' → 'MAJOR'.

Autotegs و امضای مصنوعی:

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 repo، بررسی اینکه «اصلی» همیشه به آخرین برچسب پایدار اشاره دارد.

11) سیاست محرومیت

اطلاعیه: علامت گذاری به عنوان عملکرد در نسخه MINOR منسوخ شده، به مدت EOL (به عنوان مثال 90 روز)

قابلیت مشاهده: استفاده از نقاط انتهایی میراث را با زمینه کاربر/مستاجر وارد کنید.
حذف: در زیر 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. ۲ مثالهایی از مقایسهها

`1. 2. 3` < `1. 10. 0 '(مقایسه جزئی).
`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.
پیشرفت عمده بدون خرابی واقعی («نسخه های بازاریابی»).
تغییرات شکستن پنهان تحت پوشش «PATCH».
پیش انتشارها در وابستگیهای انتقالی کاربردهای تولید.
تغییر مصنوع بدون برچسب جدید (نسخه های قابل تغییر).
نسخه های کد متناقض و طرح های پایگاه داده.

14) چک لیست پیاده سازی (0-45 روز)

0-10 روز

SemVer را به عنوان یک استاندارد اجباری بپذیرید، معیارهای شکستن را تأیید کنید.
شامل کمیته های متعارف و یک قالب PR با فیلد «BREAKING CHANGE».

11-25 روز

اتصال semantic-release/changesets، تولید خودکار CHANGELOG.
پیکربندی امضا و انتشار مصنوعات در برابر برچسب vX. آره. زي.

26-45 روز

وارد سیاست استهلاک و تله متری برای استفاده API میراث.
همگام سازی نسخه های قرارداد (OpenAPI/Proto) و خدمات.
ممنوعیت «آخرین» و برچسب های قابل تغییر در سطح سیاست (مقررات OPA/CI).

15) معیارهای بلوغ

٪ مصنوعات فقط توسط برچسب SemVer منتشر شده است.

میانگین زمان مهاجرت بین نسخه های MINOR

تعداد حوادث به دلیل تغییرات شکستن پنهان.
پوشش کمیته های متعارف در مخازن (> 95٪).
نسبت وابستگی بدون محدوده شناور در محصول (> 90٪).

16) هنگامی که SemVer مورد نیاز نیست

نمونه های داخلی سریع بدون مصرف کنندگان خارجی (نسخه سازی تاریخ مناسب است).
داده ها/مدل ها با ویژگی های تجربی (نسخه بهتر مدل/طرح با سازگاری در سطح مبدل).
بسته های محتوا بدون API عمومی پایدار.

17) نتیجه گیری

SemVer یک قرارداد اعتماد بین تولید کننده و مصرف کننده است. به وضوح تعریف آنچه می شکند سازگاری، به طور خودکار به رسمیت شناختن نوع انتشار و انتشار مصنوع، حفظ CHANGELOG شفاف، و مطابق با سیاست های محرومیت. سپس به روز رسانی ها معمول، قابل پیش بینی و امن خواهند بود - و زیرساخت ها و API ها بدون شوک به کسب و کار توسعه خواهند یافت.

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