انتقل إلى المحتوى

الإصدارات وقناة ما قبل الإصدار

كيف تُصدر Turbo EA إصداراتها وتضع وسومها وتنشر صور الحاويات. هذه الصفحة هي المرجع للمشغّلين الذين يحتاجون إلى تثبيت الإصدارات في الإنتاج وللمساهمين الذين يقطعون الإصدارات.

وضع الإصدارات

تتّبع Turbo EA الإصدارات الدلالية. المصدر الوحيد للحقيقة للإصدار الحالي هو ملف /VERSION في جذر المستودع.

  • التصحيح (مثل 1.0.0 ← 1.0.1): إصلاحات أخطاء فقط. آمن دائمًا للترقية.
  • الفرعي (مثل 1.0.0 ← 1.1.0): ميزات جديدة. متوافق رجعيًا وفق سياسة التوافق.
  • الرئيسي (مثل 1.x ← 2.0.0): تغييرات كاسرة. تأتي ملاحظات الترحيل مع الإصدار.

يُرفع الإصدار مرة واحدة لكل PR، لا لكل commit. يستخدم إدخال CHANGELOG في الـ PR الإصدار الجديد كعنوان؛ ويُفشل version-check.yml في CI أي PR يرفع VERSION دون عنوان ## [<version>] مطابق في CHANGELOG.md.

وسوم صور الحاويات

كل دفع إلى main وكل وسم v*.*.* يُشغّل .github/workflows/docker-publish.yml، الذي يبني ويدفع صورًا متعددة المعماريات (amd64 + arm64) إلى GHCR.

لوسم إصدار مثل v1.2.3، الوسوم المنشورة على كل صورة هي:

الوسم يشير إلى مستقر؟
1.2.3 ذلك الإصدار بالضبط نعم — ثبّت هذا في الإنتاج
1.2 أحدث تصحيح على 1.2.x يتدحرج إلى الأمام على التصحيحات
1 أحدث فرعي على 1.x يتدحرج إلى الأمام على الفرعيات
latest أحدث إصدار ليس ما قبل إصدار يتدحرج إلى الأمام على كل إصدار
sha-<short> الـ commit بالضبط نعم — تصحيح الأخطاء / ما قبل الإصدار

بالنسبة للدفعات إلى main (دون وسم)، يُنتَج فقط وسما main وsha-<short> — لا latest أبدًا، ولا أي وسم semver.

تُوقَّع جميع بيانات صور الحاويات المنشورة بـ cosign keyless OIDC. تفاصيل التحقق وSBOM في سلسلة التوريد.

قناة ما قبل الإصدار

بالنسبة للإصدارات الفرعية التي تغيّر تخطيط الحاوية، أو الصور الأساسية، أو معرّفات UID الافتراضية، أو أسماء وحدات التخزين، أو المنافذ الافتراضية، أو المخطط بطريقة تتطلّب إجراءً من المشغّل، يُقطع مرشّح إصدار قبل الوسم النهائي.

الأعراف:

  • وسوم RC هي vX.Y.0-rc.N — لا تكون أبدًا على إصدار تصحيح، فقط على الإصدارات الفرعية ذات التغييرات المرئية للمشغّل.
  • يُهيَّأ docker/metadata-action في سير عمل النشر بـ flavor: latest=auto. هذا يستبعد تلقائيًا وسوم ما قبل الإصدار من نوع semver من :latest و:X.Y و:X — تُنشر مرشّحات RC فقط كـ :X.Y.0-rc.N. المشغّلون الذين يثبّتون على :latest لن يسحبوا RC بالخطأ.
  • ينبغي تعليم إصدار GitHub لوسم RC كـ ما قبل إصدار في صفحة الإصدارات. سير عمل github-release.yml الحالي ينشئ دائمًا إصدارًا ليس ما قبل إصدار؛ يقلب المسؤول مفتاح ما قبل الإصدار يدويًا بعد تشغيل سير العمل (أو يحرّر الإصدار عبر gh release edit vX.Y.0-rc.N --prerelease).

وقت النضج:

  • يبقى RC منشورًا لمدة 48–72 ساعة على الأقل قبل الترقية، أو حتى يبلّغ مشغّل واحد على الأقل خارج المسؤول عن ترقية ناجحة — أيهما أطول.
  • تُشحن تقارير الأخطاء ضد RC كـ vX.Y.0-rc.N+1 إذا كانت المشكلة تستحق الإصلاح. يُترك RC السابق في GHCR لقابلية إعادة الإنتاج.

الترقية إلى النهائي:

  • يُنشأ الوسم النهائي vX.Y.0 على نفس الـ commit الخاص بآخر RC. يعيد سير عمل النشر بناء وإعادة وسم الصور متعددة المعماريات؛ سيختلف الـ digest عن RC رغم تطابق المصدر (مدخلات البناء تتضمّن طوابع زمنية).
  • تنتقل وسوم :X.Y و:X و:latest للإشارة إلى الإصدار النهائي عند هذه النقطة.

قطع إصدار (قائمة تحقق المسؤول)

لتصحيح أو إصدار فرعي عادي — دون الحاجة إلى قناة RC:

  1. على فرع ميزة، ارفع VERSION وأضف العنوان المطابق ## [<version>] - YYYY-MM-DD إلى CHANGELOG.md.
  2. شغّل python scripts/dump_openapi.py إذا تغيّر أي مسار أو مخطط في الخلفية؛ ثبّت النتيجة إن تغيّرت.
  3. افتح الـ PR. يشغّل CI الفحص اللغوي والاختبارات وفحص انحراف OpenAPI وversion-check.yml.
  4. ادمج بالضغط (squash-merge) إلى main.
  5. من main: git tag -s v<version> -m "v<version>" (أو git tag v<version> إن لم يُهيَّأ مفتاح توقيع)، git push origin v<version>.
  6. يستخرج سير عمل Publish GitHub Release قسم ## [<version>] من CHANGELOG.md وينشئ إصدار GitHub.
  7. يبني سير عمل Publish Docker images to GHCR الصور متعددة المعماريات ويوقّعها وينشرها.
  8. تحقّق باستخدام cosign: 
    cosign verify \
  --certificate-identity-regexp 'https://github.com/vincentmakes/turbo-ea/.+' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/vincentmakes/turbo-ea/backend:<version>

لإصدار فرعي يستدعي RC:

  1. نفس تدفق الـ PR والدمج أعلاه، لكن ارفع إلى 1.Y.0-rc.1.
  2. بعد الدمج، ضع وسم v1.Y.0-rc.1 وادفع. يبني سير عمل النشر صور RC ويدفعها (فقط :1.Y.0-rc.1، لا :latest أو الوسوم القصيرة أبدًا — flavor: latest=auto يتولّى ذلك). ينشئ سير عمل الإصدار إصدار GitHub؛ اقلبه يدويًا إلى ما قبل إصدار بعد ذلك عبر gh release edit v1.Y.0-rc.1 --prerelease أو في واجهة GitHub.
  3. انتظر نافذة النضج. عالج أي مشكلات مُبلَّغ عنها بـ -rc.2 و-rc.3 حسب الحاجة.
  4. للترقية: ارفع VERSION إلى 1.Y.0 في PR نهائي (إدخال CHANGELOG يدمج كل إصلاحات RC)، ادمج، ضع وسم v1.Y.0، ادفع. تشير الآن وسوم :latest والقصيرة إلى الإصدار المُرقّى.

نهاية العمر

يتلقى أحدث خط فرعي فقط إصلاحات الأمان. راجع SECURITY.md للسياسة الكاملة. الخطوط الفرعية الأقدم في نهاية العمر ولن تتلقى نقلًا عكسيًا للإصلاحات — ينبغي للمشغّلين على الإصدارات الأقدم التخطيط للترقيات عبر سياسة التوافق.