{
  "title": "سیاست نسخه‌بندی",
  "slug": "team/platform/standards/versioning-policy",
  "url": "/docs/team/platform/standards/versioning-policy",
  "frontmatter": {
    "layout": "doc",
    "title": "سیاست نسخه‌بندی",
    "description": "Semantic Versioning برای سرویس‌ها و پکیج‌ها — قوانین افزایش، پیش‌انتشار و انتشار",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-07",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "سیاست نسخه‌بندی",
      "content": "**Versioning Policy**\n\nنسخه 1.0 | الزامی برای همه سرویس‌ها، پکیج‌ها و انتشارات\n\n---"
    },
    {
      "level": 2,
      "heading": "1. استاندارد",
      "content": "همه سرویس‌ها و پکیج‌ها از **Semantic Versioning 2.0.0** پیروی می‌کنند:\n\n```\nv{MAJOR}.{MINOR}.{PATCH}\n  ^     ^     ^\n  |     |     |\n  |     |     └─── PATCH: تغییرات برگشت‌پذیر (رفع باگ، بهبود)\n  |     └───────── MINOR: افزودن قابلیت جدید (برگشت‌پذیر)\n  └─────────────── MAJOR: تغییرات ناسازگار (شکستن API)\n```\n\n**فرمت کامل:** `v{MAJOR}.{MINOR}.{PATCH}` — مثال: `v1.4.2`\n\n---"
    },
    {
      "level": 2,
      "heading": "2. قوانین افزایش نسخه",
      "content": ""
    },
    {
      "level": 3,
      "heading": "MAJOR — تغییر ناسازگار (Breaking Change)",
      "content": "- حذف یا تغییر یک endpoint\n- تغییر امضای یک رویداد (payload)\n- حذف یک فیلد از پاسخ API\n- تغییر نوع دیتابیس یا ساختار جدول\n- ارتقاء وابستگی اصلی که MAJOR خود را افزایش داده"
    },
    {
      "level": 3,
      "heading": "MINOR — افزودن قابلیت جدید",
      "content": "- اضافه کردن endpoint جدید\n- اضافه کردن فیلد جدید به پاسخ (اختیاری)\n- اضافه کردن رویداد جدید\n- اضافه کردن قابلیت جدید بدون شکستن قبلی‌ها"
    },
    {
      "level": 3,
      "heading": "PATCH — رفع باگ / بهبود",
      "content": "- رفع باگ بدون تغییر API\n- بهبود عملکرد\n- بروزرسانی وابستگی‌های فرعی\n- رفع اشکالات امنیتی جزئی\n\n---"
    },
    {
      "level": 2,
      "heading": "3. پیش‌انتشار (Pre-release)",
      "content": "برای نسخه‌های آزمایشی از برچسب‌های زیر استفاده کنید:\n\n| برچسب | معنی | مثال |\n|---|---|---|\n| `-alpha.{n}` | توسعه داخلی، ناپایدار | `1.0.0-alpha.1` |\n| `-beta.{n}` | تست محدود، احتمال تغییر | `1.0.0-beta.2` |\n| `-rc.{n}` | نامزد انتشار، پایدار اما در انتظار تأیید | `1.0.0-rc.3` |\n\n```bash\nnons/auth:v1.0.0-alpha.1\nnons/auth:v1.0.0-beta.1\nnons/auth:v1.0.0-rc.1\nnons/auth:v1.0.0\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "4. نسخه‌بندی مستقل",
      "content": "| موجودیت | نسخه مستقل | توضیح |\n|---|---|---|\n| سرویس (Service) | بله | هر سرویس نسخه مستقل خود را دارد |\n| پکیج (Package) | بله | هر پکیج نسخه مستقل خود را دارد |\n| پروژه (Monorepo) | خیر | نسخه در سطح سرویس/پکیج است |\n\n> یک سرویس ممکن است `v2.0.0` باشد در حالی که سرویس دیگر در `v1.3.5` است. این کاملاً طبیعی است.\n\n---"
    },
    {
      "level": 2,
      "heading": "5. انتشار (Release)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "چرخه انتشار",
      "content": "```\nتوسعه → تست → پیش‌انتشار → انتشار نهایی\n```"
    },
    {
      "level": 3,
      "heading": "قوانین",
      "content": "- هر انتشار باید یک **Git Tag** داشته باشد: `{service}/v{version}` \n  - مثال: `order/v1.2.0`, `nons-api/contracts/v0.4.1`\n  - برای Proto: `nons-api/contracts/v{major}.{minor}.{patch}` — هماهنگ با SemVer سرویس‌ها\n- هر انتشار باید یک **GitHub Release** داشته باشد\n- هر انتشار باید CHANGELOG به‌روز شده داشته باشد\n- انتشار بدون نسخه معتبر ممنوع است\n- پس از انتشار، نسخه قابل تغییر نیست — اگر اشتباه شد، نسخه جدید منتشر کنید\n- **تغییر Proto:** افزودن فیلد جدید ← MINOR | حذف یا تغییر فیلد ← MAJOR (توسط Buf تشخیص داده می‌شود)"
    },
    {
      "level": 3,
      "heading": "برچسب‌گذاری (Tagging)",
      "content": "```bash\ngit tag auth/v1.0.0\ngit tag order/v2.0.0-alpha.1\ngit tag nons-api/contracts/v0.4.1\ngit push origin --tags\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "6. وابستگی نسخه‌ها (Version Compatibility)",
      "content": "| سناریو | قانون |\n|---|---|\n| سرویس A به سرویس B وابسته است | سرویس A باید محدوده MAJOR سرویس B را مشخص کند |\n| پکیج به پکیج دیگر وابسته است | محدوده دقیق نسخه در `package.json` / `go.mod` |\n| نسخه سرویس در کانفیگ | نسخه سرویس باید در متغیر محیط `SERVICE_VERSION` باشد |\n\n```json\n{\n  \"dependencies\": {\n    \"@nons/contracts\": \"^1.0.0\",\n    \"@nons/events\": \"^1.0.0\"\n  }\n}\n```\n\n**نکته:** نسخه‌بندی Bindingهای تولیدشده از Proto با نسخه Proto هماهنگ است. Bindingها در CI تولید می‌شوند — ویرایش دستی نسخه Bindingها ممنوع. تایپ‌های فرانت‌اند توسط `nons generate` در `.nons/generated/types/` تولید می‌شوند."
    },
    {
      "level": 3,
      "heading": "Service Manifest و API — ماتریس سازگاری (ADR-Platform-004)",
      "content": "با تصویب [ADR-Platform-004](../ADR/ADR-Platform-004)، **Service Manifest** منبع حقیقت برای تولید مصنوعات کلاینت است. APIها از طریق Service Manifest با پروژه‌های کلاینت هماهنگ می‌شوند. جفت‌شدگی خطی ممنوع است. هر Manifest به صورت صریح مشخص می‌کند با کدام نسخه‌های فعال API سازگار است:\n\n| Manifest Version | API Version |\n| :--- | :--- |\n| 1.x | v1 |\n| 2.x | v1, v2 |\n| 3.x | v2 |\n\nبررسی سازگاری توسط `nons validate` انجام می‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "7. نسخه و Docker Image",
      "content": "هر ایمیج داکر باید با نسخه دقیق تگ شود:\n\n```\nnons/order:v1.2.0\nnons/order:v1.2.0-alpha.1\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "8. مستندات نسخه‌بندی",
      "content": "- هر سرویس باید نسخه فعلی خود را در `CHANGELOG.md` اعلام کند\n- API همیشه نسخه خود را در مسیر دارد: `/v1/`, `/v2/`\n- تغییرات MAJOR نیاز به مستندات مهاجرت (Migration Guide) دارند\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه",
      "content": "| نوع تغییر | افزایش | مثال |\n|---|---|---|\n| رفع باگ برگشت‌پذیر | PATCH | `v1.0.0` ← `v1.0.1` |\n| قابلیت جدید برگشت‌پذیر | MINOR | `v1.0.0` ← `v1.1.0` |\n| تغییر ناسازگار | MAJOR | `v1.0.0` ← `v2.0.0` |\n| پیش‌انتشار | + برچسب | `v2.0.0-alpha.1` |"
    }
  ]
}