الإصدارات والإطلاقات

الإصدارات والإطلاقات

تستخدم كاظمه أساسًا عامًّا ثابتًا مع معرّف التزام git حيّ.

الصيغة

الجزء	مثال	المعنى
الأساس العام (الملفات)	0.11.0	pyproject.toml الجذري / kazma.yaml / إصدارات الحزم
إصدار العرض	0.11.0+g4d37b2c	ما يعرضه CLI واللافتة وFastAPI والواجهة
+g……	مقطع محلي وفق PEP 440	SHA قصير لـ git ‏(g = git)

لماذا لا نرفع 0.10.0 → 0.10.1 مع كل دمج؟ لأن ذلك تحوّل في يوم واحد إلى ضجيج 0.10 → 0.11 → 0.12. الـ SHA هي هوية البناء الدقيقة؛ أما الأساس فمعلم بشري (milestone).

مصدر الحقيقة

الموضع	الدور
project.version في pyproject.toml الجذري	الأساس العام فقط (0.11.0)
agent.version في kazma.yaml	الأساس العام نفسه
kazma_core.version.get_version()	عرض وقت التشغيل: base+gSHA
وسم git ‏v0.11.0	علامة معلم اختيارية (بلا +)

from kazma_core.version import get_version, get_base_version

get_base_version()  # "0.11.0"
get_version()       # "0.11.0+g4d37b2c"  (when git / CI SHA available)

ترتيب تحليل SHA

1. KAZMA_GIT_SHA (تجاوز اختياري)
2. GITHUB_SHA (Actions)
3. git rev-parse --short=7 HEAD
4. لا SHA → اعرض الأساس وحده (حزمة wheel مثبَّتة بلا .git)

ما ليس مؤتمتًا

السلوك السابق	الآن
الدفع إلى main → رفع تلقائي للترقيع	معطَّل (.github/workflows/version-bump.yml بلا أثر)
feat: → قفزة minor	زال
CI يعيد كتابة pyproject.toml	أبدًا

متى تُغيَّر قاعدة الأساس (0.10.0 → 0.10.1 / 0.11.0)

فقط عند معلم منتج مقصود:

1. عدّل كل مواضع الأساس إلى الإصدار العام الجديد (بلا +g… في الملفات):
   • pyproject.toml
   • kazma.yaml → agent.version
   • kazma-gateway/pyproject.toml
   • kazma-tui يرجع تلقائيًا إلى kazma_core.version (لا حاجة إلى ترميز ثابت)
2. التزم بالرسالة: chore(version): base 0.10.0 → 0.10.1
3. اختياريًا شغّل Actions → Release لإنشاء الوسم v0.10.1 + إصدار GitHub Release

لا تضع +gSHA في ملفات الإصدارات المُلتزَمة. كود العرض يضيفها.

سير عمل الإطلاق اليدوي

.github/workflows/release.yml (‏workflow_dispatch فقط):

• يستخلص base من pyproject.toml + الـ SHA القصير من HEAD
• ينشئ اختياريًا وسمًا موسومًا v{base} إن لم يكن موجودًا
• ينشئ/يحدّث إصدار GitHub Release يذكر base+gSHA الكامل
• لا يعدّل ملفات الإصدارات

فحص محلي

python -c "from kazma_core.version import get_version; print(get_version())"
# → 0.10.0+g4d37b2c

ما لا يجب فعله

• لا تُعِد تفعيل الرفع التلقائي للإصدار عند الدفع إلى main
• لا تخزّن 0.10.0+g… في pyproject.toml (ضجيج في التغليف؛ الـ SHA تتقادم)