سياسة هندسة الإصدار

تحكم خمس سياسات كيفية إصدار apothem.

1. الترقيم الدلالي للنسخCopy Anchor Link

يُشحَن المشروع وفق الترقيم الدلالي للنسخ 2.0. تأخذ أرقام النسخ الشكل MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

تستخدم وسوم المرشّحين الصيغة vX.Y.Z-rc.N (مرشّح إصدار) أو vX.Y.Z-alpha.N / vX.Y.Z-beta.N (وصول مبكر).

2. وسوم الإصدارCopy Anchor Link

يضع كل إصدار وسم git موقَّعًا بالشكل vMAJOR.MINOR.PATCH على main. يُطلِق الوسم .github/workflows/release.yml الذي يبني، ويوقّع، ويولّد SBOM والمنشأ SLSA-3، وينشر صفحة إصدار GitHub.

أعراف الوسوم:

• الصيغة — vMAJOR.MINOR.PATCH بالضبط. بلا بادئة release-، ولا لاحقة -final.
• التعليق التوضيحي — كل وسم هو وسم مُعلَّق (git tag -a -s) يحمل ملخّص ملاحظات الإصدار في رسالة الوسم.
• التوقيع — كل وسم موقَّع بـ GPG. ويُنتج سير عمل الإصدار إضافةً إلى ذلك توقيع cosign بلا مفاتيح عبر Sigstore على كل قِطعة، وسجلّ منشأ SLSA-3، وكلاهما مُرفَق بصفحة إصدار GitHub.

نموذج الإصدار: تراكميCopy Anchor Link

الإصدارات تراكمية. يضيف كل إصدار كوميتًا واحدًا على main ووسمًا واحدًا؛ ولا يُدفَع main بالقوة أبدًا، ولا يُحذَف أيٌّ مما نُشِر من وسوم أو إصدارات GitHub أو نسخ npm، ولا يُنقَل، ولا يُعاد استخدامه. يحتفظ كل إصدار بوسمه وإصدار GitHub الخاص به ونسخة npm الخاصة به، وتبقى جميعها منشورة. نسخ npm غير قابلة للتغيير: لا يمكن أبدًا استبدال name@version منشور، ولا يمكن أبدًا استخدام رقم أُلغي نشره مرة أخرى. تعتمد عمليات التثبيت المقيّدة بنسخة محدّدة وعمليات البناء القابلة لإعادة الإنتاج على كل وسم منشور. ويتبع دليلا التشغيل دورة الإصدار واسترداد الإصدار كلاهما هذا النموذج.

تنصّ قاعدة واجهة الإصدار في المستودع (قسم Release Facade في تعليمات المساهمين) على هذا النموذج. ويسري شرطُ الإصدار الحالي فقط، الذي تعكسه قاعدة واجهة الحداثة، على ما تقوله الأسطح العامة. ولا يحدّ من الإصدارات التي تبقى منشورةً.

3. سياسة الإهمالCopy Anchor Link

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

إيقاع الإهمال:

• الإعلان — يُعلَن عن أي رمز أو سلوك مُهمَل في قسم ### Deprecated من CHANGELOG.md الخاص بالإصدار الذي يصل فيه الإهمال. وتعكس ملاحظات الإصدار إعلان الإهمال.
• نافذة السماح — تظل الرموز المُهمَلة متاحة لمدة دورة ثانوية كاملة واحدة على الأقل قبل الإزالة.
• الإزالة — تصل الإزالة في رفع MAJOR. ويحمل كل رمز مُزال سطر ### Removed في CHANGELOG.md ومدخل دليل ترحيل ضمن الأدلة الإرشادية.

الحدود الدنيا لبيئة التشغيلCopy Anchor Link

يُعلِن Apothem حدّين أدنيين لبيئة التشغيل: requires-python = ">=3.10" في pyproject.toml و"engines": {"node": ">=18"} في package.json.

• كل حدّ أدنى مُعلَن مُختبَر. يعمل الحدّ الأدنى لـ Python في مصفوفة quality ضمن CI وفي سير عمل CI Matrix. ويُشغِّل سير عمل npm Shim غلاف npm على الحدّ الأدنى لـ Node وعلى كل إصدار رئيسي لاحق من فئة LTS: فهو يفحص خطأ المتطلّب المُسبق المفقود، وnode bin/apothem.mjs --version، وتثبيتًا تجريبيًا في دليل منزلي معزول، والأرشيف المُحزَّم عبر npx. بيئة التشغيل غير المُختبَرة لا تُعلَن.
• يُفصَح عن انتهاء العمر. عندما تبلغ بيئة تشغيل لا تزال حدًّا أدنى مُعلَنًا نهايةَ عمرها لدى المصدر الأصلي، يذكر دليل التثبيت ذلك ويُسمّي النسخ التي يُفضَّل استخدامها. بلغ Python 3.10 نهاية عمره في 2026-10-01؛ وبلغ Node.js 18 و20 نهاية عمرهما في 2025-04-30 و2026-04-30. تظل الثلاثة جميعها حدودًا دنيا مدعومة.
• رفع الحدّ الأدنى إهمالٌ. يتبع الإيقاع أعلاه: إعلان تحت ### Deprecated، ثم دورة ثانوية كاملة واحدة على الأقل يظل فيها الحدّ الأدنى القديم مُختبَرًا، ثم يُسجِّل الإصدارُ الذي يرفعه التغييرَ. وتتغيّر requires-python وengines.node ومجسّات النسخ في المثبِّتات ومصفوفات CI معًا في ذلك الإصدار.

4. سياسة التغييرات الكاسرةCopy Anchor Link

تتطلّب التغييرات الكاسرة:

1. مسألة RFC — تُفتَح تحت تسمية المسائل rfcs، وتصف التغيير الكاسر، ومسار الترحيل، واستراتيجية التراجع.
2. نافذة تعليقات مدّتها 30 يومًا — تظل الـ RFC مفتوحة 30 يومًا على الأقل قبل الدمج. ويجوز للمشرفين تمديد النافذة عندما تستدعي الملاحظات ذلك.
3. رفع MAJOR — الإصدار الذي يُدخِل التغيير الكاسر يرفع مكوّن MAJOR.
4. دليل ترحيل — يُشحَن التغيير مع مدخل في الأدلة الإرشادية يقود المُشغِّل خلال الترحيل.

5. سياسة التراجعCopy Anchor Link

إذا أظهر إصدارٌ انحدارًا يعيق التبنّي:

1. العكس — يُعكَس الكوميت (أو الكوميتات) المُسبِّب للخلل على main.
2. إصدار إصلاح إلى الأمام — يصدر إصدار متابعة بوصفه vMAJOR.MINOR.PATCH+1 يحمل العكس إضافةً إلى أي إصلاحات تدريجية. لا يُحذَف الإصدار المعيب السابق من إصدارات GitHub، وتبقى نسخته على npm منشورة (نسخ npm غير قابلة للتغيير) وتُعلَّم بـ npm deprecate. ويوثّق تعليقٌ توضيحي ### Yanked في CHANGELOG.md الوضعَ لتبقى عمليات البناء القابلة لإعادة الإنتاج مرتكزة على مرجع ثابت.
3. التواصل — يصاحب التراجعَ إشعارٌ في security-advisories (عندما يكون متعلقًا بالأمن) أو مسألة GitHub مُثبَّتة للحادثة (عندما يكون متعلقًا بالموثوقية).

انظر أيضًاCopy Anchor Link

• CHANGELOG.md — سجلّ الإصدارات المرجعي.
• SECURITY.md — مصفوفة النسخ المدعومة وقنوات الإبلاغ.
• cicd-pipeline.md — فئات فحوص CI التي تحرس بوابة كل إصدار.
• deployment-checklist.md — مسح الجاهزية للإنتاج لكل إصدار.