دليل تشغيل استرداد الإصدار
إجراءات استرداد إصدار يفشل أثناء تنفيذه ضمن نموذج الإصدار التراكمي، مرحلةً بمرحلة، دون إعادة كتابة التاريخ المنشور.
يستعيد دليل التشغيل هذا حالةً عاملة عندما يفشل إصدار vX.Y.Z من
ahmed-g-gad/apothem في منتصف الطريق. ويتبع نموذج الإصدار نفسه الذي
يتبعه دليل تشغيل دورة الإصدار: نموذجًا تراكميًا.
يضيف كل إصدار كوميتًا واحدًا على main ووسمًا واحدًا موقَّعًا ومُعلَّقًا؛
ويُشغِّل دفعُ الوسم سيرَي عمل الإصدار وnpm. لا يُدفَع أي شيء بالقوة،
ولا يُعاد أبدًا كتابة التاريخ على main.
التاريخ المنشور دائم. يبقى منشورًا كلُّ وسم إصدار، وكلُّ إصدار GitHub،
وكلُّ نسخة npm نشرها المشروع. نسخ npm
غير قابلة للتغيير: لا يمكن أبدًا استبدال name@version منشور، ولا يمكن
أبدًا استخدام رقم نسخة أُلغي نشره مرة أخرى. لذلك يمضي الاسترداد إلى الأمام بإصدار
تصحيحي جديد؛ فهو لا يحذف ولا يُعيد توجيه أي شيء ربما يكون المستخدم قد ثبّته بالفعل.
1. تصنيف المراحل
| المرحلة | الإجراء | نمط الفشل | مسار الاسترداد |
|---|---|---|---|
| 1 | إنزال كوميت الإصدار على main (القسم 2.1 من دليل تشغيل دورة الإصدار) | يفشل CI على كوميت الإصدار | أصلِح إلى الأمام بكوميت آخر على main؛ لا تضع الوسم حتى يصبح CI أخضر |
| 2 | دفع الوسم الموقَّع والمُعلَّق | يُرفَض الدفع، أو يكون الوسم غير موقَّع أو على الكوميت الخطأ | القسم 2 أدناه |
| 3 | يبني release.yml إصدار GitHub ويوقّعه وينشره | تفشل إحدى المهام، أو تكون الأصول مفقودة | القسم 3 أدناه |
| 4 | ينشر publish-npm.yml الحزمة @ahmed-g-gad/apothem (ويعمل على دفع الوسم نفسه) | يفشل النشر | القسم 3 أدناه |
| 5 | Pages والبيانات الوصفية للمستودع | الموقع أو البيانات الوصفية قديمة | القسم 3 أدناه |
كل إجراء استرداد متماثل الأثر عند تكراره. تشغيله على حالة نظيفة لا يفعل شيئًا؛ وتشغيله على حالة جزئية يستعيد الحالة المتوقَّعة لما بعد المرحلة.
2. استرداد الوسم
شخِّص الوسم:
git fetch origin --tags
git ls-remote origin refs/tags/vX.Y.Z
git cat-file -t vX.Y.Z # "tag" for an annotated tag
git tag -v vX.Y.Z # signature checkيتوقف ما تفعله على ما إذا كان أي شيء قد نُشِر من الوسم:
-
لم يُنشَر شيء بعد (فشل سير عمل الإصدار قبل مهمة النشر الخاصة به، ولم ينشر
publish-npm.ymlشيئًا): احذف الوسم وأعِد وضع الوسم على الكوميت نفسه باستخدام-a -s.git push --delete origin vX.Y.Z git tag -d vX.Y.Z git tag -a -s vX.Y.Z -m "vX.Y.Z" <release-commit-sha> git push origin vX.Y.Z -
نُشِر أي شيء (إصدار GitHub بأصول، أو نسخة npm): لا تنقل الوسم أبدًا، ولا تحذفه، ولا تُعِد استخدامه. أصلِح إلى الأمام بـ
vX.Y.(Z+1).
لا يُعاد أبدًا استخدام اسم وسم لكوميت مختلف.
3. استرداد الناشرين
يُعاد تشغيل كل ناشر بمفرده:
| السطح | التشخيص | الاسترداد |
|---|---|---|
| سير عمل الإصدار | يُسمّي gh run view <run-id> --log المهمة الفاشلة | gh run rerun <run-id> --failed. يعني الفشل عند Check the plugin version changed with the plugin أن رقم النسخة لم يُرفَع: راجع جدول حالات الفشل في دليل تشغيل دورة الإصدار |
| إصدار GitHub | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | أعِد تشغيل مهمة publish GitHub Release؛ فهي تُعدِّل الإصدار الموجود وتُعيد رفع الأصول باستخدام --clobber |
| npm | npm view @ahmed-g-gad/apothem version وnpx @ahmed-g-gad/[email protected] --version | أعِد تشغيل publish-npm.yml لـ vX.Y.Z (gh workflow run publish-npm.yml --field tag=vX.Y.Z) بعد التأكد من تفعيل النشر الموثوق في npm للحزمة. إذا كانت النسخة موجودة بالفعل في السجلّ، يتخطّى سير العمل النشر، لأن نسخ npm غير قابلة للتغيير |
| 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 |
| البيانات الوصفية للمستودع | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | رقِّع الوصف والصفحة الرئيسية والمواضيع في مكانها؛ لا تُعِد إنشاء المستودع أبدًا |
4. التراجع
يُتراجَع عن الإصدار المعيب بإصدار إصلاحه، لا بإزالته:
-
اعكِس الكوميتات المُسبِّبة للخلل على
main(كوميت عكس عادي). -
أصدِر
vX.Y.(Z+1)باتباع دليل تشغيل دورة الإصدار. -
علِّم النسخة المعيبة: أضِف ملاحظة
### Yankedإلى قسمها فيCHANGELOG.md، وعدِّل ملاحظات إصدار GitHub الخاص بها لتشير إلى الإصلاح، وأعلِن إهمالها على npm:npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
يبقى الوسم المعيب وإصدار GitHub ونسخة npm منشورة، بحيث تظل عمليات التثبيت المقيّدة بنسخة محدّدة وعمليات البناء القابلة لإعادة الإنتاج قابلةً للحلّ. سجِّل التراجع بوصفه حادثة إصدار.
5. قاعدة واجهة الإصدار
تنصّ قاعدة واجهة الإصدار في المستودع (قسم Release Facade في تعليمات المساهمين) على النموذج التراكمي المذكور أعلاه: يبقى منشورًا كلُّ ما نُشِر من وسوم وإصدارات GitHub ونسخ npm. ويسري شرطُ الإصدار الحالي فقط على ما تقوله الأسطح العامة. ولا يحذف هذا الدليل أبدًا وسمًا منشورًا أو إصدار GitHub أو نسخة npm، ولا يُعيد كتابة أيٍّ منها.
6. الإحالات المرجعية
- إجراء الإصدار: دليل تشغيل دورة الإصدار.
- سياسة الإصدار: سياسة هندسة الإصدار.
- كائنات الوسوم وكيفية التحقق من كلٍّ منها: قسم توقيع الإصدارات في SECURITY.md.
- إعداد Pages:
site/content/docs/runbooks/pages-enablement.mdx.