دليل تشغيل استرداد الإصدار

إجراءات الاسترداد لإعادة المستودع إلى حالة عاملة عندما يفشل تسلسل إصدار في منتصف الطريق، مع تشخيصات مرحلة بمرحلة.

يعيد دليل التشغيل هذا ahmed-g-gad/apothem إلى حالة عاملة عندما يفشل تسلسل إصدار من نوع التطهير الكامل في المكان في منتصف الطريق. لا يُحذف المستودع العام ولا يُعاد إنشاؤه أثناء الإصدار. يعتمد الاسترداد على وسم أمان التاريخ الخاص بالإصدار، والنسخة المحلية للمشرف، وحالة مدير الحِزَم في المراحل اللاحقة.

1. تصنيف المراحل

المرحلة	الإجراء	وضع الفشل	مسار الاسترداد
1	التقاط وسم أمان التاريخ ودفعه	الوسم مفقود، أو غير موقَّع، أو يشير إلى الرسم البياني الخطأ	أعد إنشاء الوسم من نقطة الدمج قبل السحق قبل تحريك `main`
2	التحقق من CI وقلعة التدقيق وحالة الحِزَم وسجل التغييرات	فشل أيّ بوابة	توقَّف؛ أصلِح محليًا؛ لا تُحرِّك `main`
3	تحريك `main` إلى كوميت الإصدار الموقَّع الواحد	فشل force-with-lease، أو الكوميت غير موقَّع، أو رسالة الكوميت خاطئة	أعِد ضبط `main` المحلي إلى الكوميت الموقَّع المقصود وأعِد المحاولة بِـlease جديد
4	نشر إصدار GitHub وPages وnpm والبيانات الوصفية	فشل ناشر أو سطح تحقُّق	احتفظ بكوميت الإصدار؛ أعِد تشغيل الناشر الفاشل وحده بعد تسجيل الفشل

كل إجراء استرداد عديم الأثر (idempotent). تشغيله على حالة نظيفة لا يفعل شيئًا؛ وتشغيله على حالة جزئية يعيد الشرط المتوقَّع لما بعد المرحلة.

2. استرداد وسم الأمان

تحقَّق من وسم الأمان قبل أيّ إعادة كتابة للتاريخ:

git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>

المتوقَّع: الوسم موجود، ويَنجح التحقُّق من التوقيع عندما يكون الوسم موقَّعًا، ويمكن الوصول إلى الرسم البياني الكامل قبل السحق من الوسم. إذا كان الوسم مفقودًا محليًا لكنه موجود عن بُعد، فاجلِبه. وإذا كان مفقودًا عن بُعد، فأوقِف الإصدار وأعِد إنشاءه قبل لمس main:

git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>

3. استرداد الفرع الرئيسي

شخِّص حالة main العامة:

gh api repos/ahmed-g-gad/apothem/commits/main \
  --jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'

المتوقَّع بعد التبديل: الرسالة هي بالضبط release: Apothem <release-version> وverification.verified هي true.

إذا فشل دفع force-with-lease قبل تغيير GitHub، فاترك المستودع البعيد كما هو، واجلِبه، وأعِد بناء كوميت الإصدار الموقَّع محليًا، ولا تُعِد المحاولة إلا بعد أن يتطابق الـlease:

git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin main

إذا هبط الدفع بكوميت غير موقَّع أو غير مُتحقَّق منه، فأصلِح إعداد التوقيع المحلي، وأعِد إنشاء كوميت الإصدار من الشجرة نفسها، وادفع بالقوة مرة أخرى بِـlease. لا تحذف وسم الأمان.

4. استرداد الناشرين

يُعاد تشغيل كل ناشر بشكل مستقل بعد التحقُّق من كوميت إصدار GitHub:

السطح	التشخيص	الاسترداد
إصدار GitHub	`gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets`	احذف فقط المسودّة المُشوَّهة؛ وإلا فارفع الأصول المفقودة بِـ`gh release upload --clobber`
وسم الإصدار	`git ls-remote origin refs/tags/<release-tag>` و`git tag -v <release-tag>`	أعِد الوسم من نفس الـSHA بِـ`-a -s` إذا كان الوسم مفقودًا أو غير موقَّع؛ ولا تُعِد أبدًا استخدام اسم وسم لكوميت مختلف
npm	`npm view @ahmed-g-gad/apothem version` و`npx @ahmed-g-gad/apothem@<version> --version`	أعِد تشغيل `publish-npm.yml` لِـ`<release-tag>` بعد تأكيد npm Trusted Publishing لِـ`@ahmed-g-gad/apothem`
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` و`curl -sSI https://apothem.ahmedgad.com/`	أعِد تشغيل `publish-static-site.yml`؛ وتحقَّق من أن الـCNAME لا يزال يُحَلّ إلى `ahmed-g-gad.github.io`
البيانات الوصفية لـGitHub	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	رقِّع الوصف والصفحة الرئيسية والمواضيع في المكان؛ لا تُعِد إنشاء المستودع

5. التراجع

التراجع هو الملاذ الأخير. فضِّل استرداد الناشرين الموجَّه أولًا. إذا تعيَّن التراجع عن كوميت الإصدار الواحد، فاستعِد main من وسم الأمان:

git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin main

بعد التراجع، أعِد تشغيل CI، وأعِد تطبيق حماية الفرع إذا أبلغ GitHub عن انحراف، وسجِّل التراجع بوصفه حادثًا يحجب الإصدار. احتفظ بوسم الإصدار فقط إذا ظلَّت مُخرَجات الإصدار صالحة؛ وإلا فاحذف الإصدار والوسم المُشوَّهين قبل إعادة المحاولة.

6. الإحالات المرجعية

إعداد Pages: site/content/docs/runbooks/pages-enablement.mdx.
إجراء الإصدار: site/content/docs/runbooks/release-cycle.mdx.
وصفات التحزيم: packaging/README.md.
مرساة الاسترداد: وسم أمان التاريخ الخاص بالإصدار.