قاعدة المعرفة: عملية التحديث الذاتي

كيف يعمل triggerfish update، وما يمكن أن يحدث خطأ، وكيفية الاسترداد.

كيف يعمل

يقوم أمر التحديث بتنزيل وتثبيت أحدث إصدار من GitHub:

1. فحص الإصدار. يجلب أحدث وسم إصدار من GitHub API. إذا كنت بالفعل على أحدث إصدار، يخرج مبكراً:

   Already up to date (v0.4.2)

   بناءات التطوير (VERSION=dev) تتخطى فحص الإصدار وتتابع دائماً.

2. اكتشاف المنصة. يحدد اسم أصل الملف التنفيذي الصحيح بناءً على نظام التشغيل والمعمارية (linux-x64، linux-arm64، macos-x64، macos-arm64، windows-x64).

3. التنزيل. يجلب الملف التنفيذي وSHA256SUMS.txt من إصدار GitHub.

4. التحقق من المجموع الاختباري. يحسب SHA256 للملف التنفيذي المُنزَّل ويقارنه بالإدخال في SHA256SUMS.txt. إذا لم تتطابق المجاميع، يُلغى التحديث.

5. إيقاف الخدمة الخلفية. يوقف الخدمة الخلفية العاملة قبل استبدال الملف التنفيذي.

6. استبدال الملف التنفيذي. خاص بالمنصة:

   • Linux/macOS: يُعيد تسمية الملف التنفيذي القديم، ينقل الجديد إلى مكانه
   • خطوة إضافية لـ macOS: يمسح سمات العزل بـ xattr -cr
   • Windows: يُعيد تسمية الملف التنفيذي القديم إلى .old (Windows لا يستطيع الكتابة فوق ملف تنفيذي قيد التشغيل)، ثم ينسخ الملف التنفيذي الجديد إلى المسار الأصلي

7. إعادة تشغيل الخدمة الخلفية. يبدأ الخدمة الخلفية بالملف التنفيذي الجديد.

8. سجل التغييرات. يجلب ويعرض ملاحظات الإصدار للإصدار الجديد.

تصعيد Sudo

إذا كان الملف التنفيذي مثبتاً في مجلد يتطلب صلاحيات الجذر (مثل /usr/local/bin)، يطلب المُحدّث كلمة مرورك للتصعيد بـ sudo.

النقل عبر أنظمة الملفات

إذا كان مجلد التنزيل ومجلد التثبيت على أنظمة ملفات مختلفة (شائع مع /tmp على قسم منفصل)، ستفشل إعادة التسمية الذرية. يعود المُحدّث إلى نسخ-ثم-حذف، وهو آمن لكنه يحتفظ بكلا الملفين التنفيذيين على القرص لفترة وجيزة.

ما يمكن أن يحدث خطأ

"Checksum verification exception"

الملف التنفيذي المُنزَّل لا يتطابق مع التجزئة المتوقعة. هذا يعني عادة:

• التنزيل تلف (مشكلة شبكة)
• أصول الإصدار قديمة أو مرفوعة جزئياً

الحل: انتظر بضع دقائق وحاول مرة أخرى. إذا استمر، نزّل الملف التنفيذي يدوياً من صفحة الإصدارات.

"Asset not found in SHA256SUMS.txt"

نُشر الإصدار بدون مجموع اختباري لمنصتك. هذه مشكلة في خط أنابيب الإصدار.

الحل: قدّم بلاغاً على GitHub.

"Binary replacement failed"

لم يستطع المُحدّث استبدال الملف التنفيذي القديم بالجديد. الأسباب الشائعة:

• أذونات الملفات (الملف التنفيذي مملوك لـ root لكنك تعمل كمستخدم عادي)
• الملف مقفل (Windows: عملية أخرى تحتفظ بالملف التنفيذي مفتوحاً)
• نظام ملفات للقراءة فقط

الحل:

1. أوقف الخدمة الخلفية يدوياً: triggerfish stop
2. اقتل أي عمليات قديمة
3. حاول التحديث مرة أخرى بالأذونات المناسبة

"Checksum file download failed"

لا يمكن تنزيل SHA256SUMS.txt من إصدار GitHub. تحقق من اتصال شبكتك وحاول مرة أخرى.

تنظيف ملف .old على Windows

بعد تحديث Windows، يُعاد تسمية الملف التنفيذي القديم إلى triggerfish.exe.old. يُنظَّف هذا الملف تلقائياً عند البدء التالي. إذا لم يُنظَّف (مثلاً الملف التنفيذي الجديد تعطّل عند البدء)، يمكنك حذفه يدوياً.

مقارنة الإصدارات

يستخدم المُحدّث مقارنة الإصدار الدلالي:

• يزيل بادئة v (كل من v0.4.2 و0.4.2 مقبولتان)
• يقارن الرئيسي والثانوي والتصحيح رقمياً
• تُعالج إصدارات ما قبل الإطلاق (مثل v0.4.2-rc.1)

التحديث اليدوي

إذا لم يعمل المُحدّث التلقائي:

1. نزّل الملف التنفيذي لمنصتك من إصدارات GitHub
2. أوقف الخدمة الخلفية: triggerfish stop
3. استبدل الملف التنفيذي:

   # Linux/macOS
   sudo cp triggerfish-linux-x64 /usr/local/bin/triggerfish
   sudo chmod +x /usr/local/bin/triggerfish
   
   # macOS: امسح العزل
   xattr -cr /usr/local/bin/triggerfish

4. ابدأ الخدمة الخلفية: triggerfish start

تحديث Docker

عمليات نشر Docker لا تستخدم المُحدّث التنفيذي. حدّث صورة الحاوية:

# باستخدام السكربت المُغلّف
triggerfish update

# يدوياً
docker compose pull
docker compose up -d

يسحب السكربت المُغلّف أحدث صورة ويُعيد تشغيل الحاوية إذا كانت تعمل.

سجل التغييرات

بعد التحديث، تُعرض ملاحظات الإصدار تلقائياً. يمكنك أيضاً عرضها يدوياً:

triggerfish changelog              # الإصدار الحالي
triggerfish changelog --latest 5   # آخر 5 إصدارات

إذا فشل جلب سجل التغييرات بعد التحديث، يُسجَّل لكنه لا يؤثر على التحديث نفسه.