دليل تشغيل دورة الإصدار

يقود دليل التشغيل هذا إصدار vX.Y.Z لـapothem من شجرة عمل نظيفة إلى أسطح توزيع مُتحقَّق منها. كُتب الإجراء للمشرف الذي يستخدم gh وgit وصدفة طبقة الإصدار؛ وينتهي بصفحة Release مُتحقَّق منها، وCHANGELOG مُعبَّأ، واختبار دخان لمسار التثبيت يؤكد أن كل سطح يواجه المستخدم يستجيب لأمر التثبيت المعياري.

شكل الإصدار وسم واحد، مرحلتان. وسم إصدار موقَّع واحد على main يُشغِّل .github/workflows/release.yml، الذي يبني ويُوقِّع ويُشهِد ويَنشُر إصدار GitHub بمجموعة الأدوات الكاملة الخاصة به — sdist وwheel وCycloneDX SBOM وحُزم Sigstore cosign ومنشأ SLSA-3 وأرشيفات وقت تشغيل المنصة. المرحلة الثانية الاختيارية هي إرسال يدوي لـpublish-npm.yml، الذي ينشر @ahmed-g-gad/apothem على npmjs.com بعد أن يصبح scripts/release/check-release-ready.sh أخضر. يُكتب قسم CHANGELOG المُرقَّم بالإصدار جنبًا إلى جنب مع كوميت الوسم؛ يُشغِّل المُشغِّل اختبار دخان مسار التثبيت بعد هبوط كلتا المرحلتين.

1. المتطلبات المسبقة

يؤكد المشرف ما يلي قبل الوسم:

• شجرة العمل. نظيفة (git status لا يُظهر شيئًا معلَّقًا). كل عمل المزايا الخاص بالإصدار موجود على main.

• CI أخضر. أحدث main يُرجِع gh run list --branch=main --limit=1 --json conclusion --jq '.[0].conclusion' القيمة success.

• الأدوات. gh (GitHub CLI) الإصدار 2.40 أو أحدث، مُصادَقًا عليه مقابل ahmed-g-gad؛ وgit 2.40 أو أحدث مع تحميل مفتاح توقيع GPG الفرعي؛ ورابط الناشر الموثوق لـnpm الخاص بـ@ahmed-g-gad/apothem نشط (مُتحقَّق منه وفق دليل تشغيل إعداد حساب الناشر).

• مراسي الإصدار متوائمة. سلسلة الإصدار المُعلَنة في pyproject.toml تطابق الوسم المخطط له دون البادئة v. تحقَّق:

  grep '^version' pyproject.toml

  المخرجات المتوقعة (لإصدار vX.Y.Z؛ النوائب تُمثِّل وسم الإصدار الجاري):

  version = "X.Y.Z"

• قسم CHANGELOG مُجهَّز. يحمل CHANGELOG.md قسمًا مُرقَّمًا بالإصدار تحت عناوين Keep-a-Changelog. يُحدِّث المشرف التاريخ ونقاط الإصدار في الكوميت نفسه الذي يُهبِط الوسم.

2. الوسم والتشغيل

2.1 تأليف كوميت الإصدار

يُهبِط كوميت الإصدار تغييرَين:

• قسم إصدار CHANGELOG.md مُؤرَّخ بتاريخ UTC الفعلي للإصدار.
• إصدار pyproject.toml مرفوع إلى الإصدار الجديد (فقط عندما يحمل الكوميت السابق على main بالفعل تثبيت الإصدار السابق وتلزم زيادة جديدة؛ قد يهبط الكوميت أيضًا أثناء دورة رفع الإصدار قبل وقت الوسم بأيام).

كوميت مثال:

git checkout main
git pull --ff-only origin main
# Author CHANGELOG and pyproject.toml edits via Edit tool, then:
git add CHANGELOG.md pyproject.toml
git commit -S -m "chore(release): cut vX.Y.Z"
git push origin main

تُوقِّع الراية -S الكوميت بمفتاح GPG. يُشغِّل الدفع مصفوفة CI القياسية (lint وtest وbuild)؛ انتظر الأخضر قبل الوسم.

2.2 توقيع الوسم ودفعه

git tag -a -s vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

يُنتج تركيب -a -s وسمًا مُعلَّقًا موقَّعًا بـGPG. يُشغِّل الدفع .github/workflows/release.yml، الذي يبني ويُوقِّع ويُشهِد ويَنشُر.

2.3 تأكيد اكتمال سير عمل الإصدار

gh run watch $(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId')

يُشغِّل سير العمل البناء (sdist + wheel)، وتوليد SBOM (CycloneDX)، وتوقيع cosign دون مفتاح، وتوليد منشأ SLSA-3 والتحقق منه، وبناء أرشيفات المنصة (darwin / linux / windows)، وتوقيع الأرشيفات بملف بيان SHA256SUMS مُجمَّع، ونشر إصدار GitHub النهائي. يفحص المشرف سجل مهمة publish GitHub Release بحثًا عن تأكيدات رفع الأصول.

2.4 إرسال نشر npm (مرحلة اختيارية)

بعد أن يصبح إصدار GitHub وبوابة الجاهزية أخضرَين:

bash scripts/release/check-release-ready.sh vX.Y.Z
gh workflow run publish-npm.yml --field tag=vX.Y.Z

اعتمد نشر بيئة npmjs عند المطالبة. يَنشُر سير العمل @ahmed-g-gad/[email protected] على npmjs.com عبر npm Trusted Publishing (OIDC)؛ لا يُخزَّن أي رمز سجل في المستودع.

3. أسطح التوزيع

يملك كل سطح أمر تحقق يجيب على «هل هبط الإصدار هنا؟»:

إصدار GitHub هو سطح الأدوات المعياري؛ وحزمة npm ومُثبِّتات السكربت هي مسارات التثبيت المُركَّبة فوقه. نشر npm هو عمدًا المرحلة الأخيرة.

4. انضباط CHANGELOG

يحمل CHANGELOG.md قسمًا واحدًا لكل إصدار وفق اتفاقية Keep-a-Changelog. تعديل CHANGELOG في كوميت الإصدار:

• يؤكد أن قسم الإصدار يستخدم العنوان ## [X.Y.Z] — YYYY-MM-DD.
• يؤكد أن العناوين القياسية — Added، Changed، Deprecated، Removed، Fixed، Security — تُستخدَم حيثما ينطبق. تُسقَط العناوين الفارغة من الملف المُعروَض.
• يلتقط القدرات، لا التنفيذ. لغة المجال فقط؛ لا مراجع داخلية للخطة؛ لا تجزئات كوميت؛ لا مُعرِّفات خطة أو مرحلة.

قسم CHANGELOG الذي نجا من مراجعة المشرف يُقرأ بوصفه مرساة ملاحظات الإصدار لسرد الإعلان.

5. اختبار دخان مسار التثبيت

بعد اكتمال كلتا المرحلتين، يُشغِّل المشرف اختبار الدخان. اختبار الدخان هو التحقق المعياري من أن أوامر التثبيت التي تواجه المستخدم تستجيب.

5.1 إضافة Claude Code

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

المتوقع: تُثبَّت الإضافة وتصبح أوامر apothem متاحة داخل Claude Code.

5.2 Node.js (npx)

npx @ahmed-g-gad/[email protected] --version

المخرجات المتوقعة: apothem X.Y.Z.

5.3 مُثبِّت سكربت بخطوة واحدة (POSIX)

curl -fsSL https://apothem.ahmedgad.com/install.sh | sh
apothem --version

المخرجات المتوقعة: apothem X.Y.Z.

5.4 مُثبِّت سكربت بخطوة واحدة (Windows)

irm https://apothem.ahmedgad.com/install.ps1 | iex
apothem --version

المخرجات المتوقعة: apothem X.Y.Z.

5.5 التحقق من الأدوات (دليل سلسلة التوريد)

gh release download vX.Y.Z --pattern 'apothem-X.Y.Z*' --pattern '*.cosign.bundle'
cosign verify-blob \
  --bundle apothem-X.Y.Z-py3-none-any.whl.cosign.bundle \
  --certificate-identity-regexp 'github.com/ahmed-g-gad/apothem' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  apothem-X.Y.Z-py3-none-any.whl
bash scripts/release/verify-provenance.sh vX.Y.Z

المتوقع: يخرج كلا التحققَين بالقيمة 0.

يُنتج اختبار الدخان صفًا واحدًا PASS / FAIL لكل سطح؛ سجِّل الصفوف في سجل إصدار المشرف.

6. التعافي من الفشل

يملك سير عمل الإصدار أنماط فشل موثَّقة لمحرك الإصدار وناشر npm:

إذا فشلت دورة تعافٍ في إهباط سطح خلال تمريرة تشخيصية واحدة، يُسجَّل السطح بوصفه فشلًا معروفًا في ملاحظات الإصدار مع رابط للمشكلة المفتوحة؛ ويُوجَّه المستخدمون النهائيون إلى الأسطح العاملة بينما يُصلَح السطح المعطوب في إصدار تصحيحي.

7. المراجع المتقاطعة

• إعداد الناشر. دليل تشغيل إعداد حساب الناشر يُؤسِّس رابط الناشر الموثوق لـnpm والمتطلبات المسبقة على جانب GitHub التي يفترضها دليل التشغيل هذا.
• تدفق التعافي. دليل تشغيل تعافي الإصدار (site/content/docs/runbooks/release-recovery.mdx) يحكم مسار الفشل عبر المراحل أثناء انتقال الإصدار، لا حالات فشل الإصدار لكل سطح المُسمَّاة في §6.
• تفعيل Pages. يتحقق سير العمل publish-static-site.yml من موقع المشروع ويَنشُره على النطاق المخصص؛ ودليل تشغيل تفعيل Pages (site/content/docs/runbooks/pages-enablement.mdx) هو الإجراء الأعلى الذي أسَّس النطاق المخصص في المقام الأول.
• سياسة الإصدارات. site/content/docs/governance/release-engineering-policy.mdx يحمل سياسة SemVer + التوقيع + الإهمال التي يحترمها دليل التشغيل هذا.