قوالب سير العمل

تشرح هذه الوثيقة كيفية إعداد سير عمل التكامل المستمر (CI) لمسار لغة على Exercism باستخدام GitHub Actions (GHA). وهي تقدّم أفضل الممارسات وأمثلة يمكنك استخدامها لبناء سير عمل CI خاص بك يكون سريعًا وموثوقًا ومتينًا. ويمكن تكييف سير عمل GHA الموجودة في هذا المجلد لتعمل مع أي نظام CI، لأن البنية الأساسية ستبقى كما هي.

وهي:

  • ترسم ملامح سير عمل CI المثالي
  • تناقش الاعتبارات والتوصيات
  • تقدّم لك بعض القوالب لاستخدامها
  • وتتركك مع دليل للانتقال من Travis

يمكن العثور على مثال لتنفيذ ملفات سير العمل هذه في exercism/javascript.

مساعدة: يبدو هذا كعمل كثير 😓

الغرض من بقية الوثيقة هو شرح كيفية عمل سير العمل. إذا كنت في عجلة من أمرك، وتريد فقط الانتقال من Travis أو Circle إلى GHA دون تحسين نصوص PR، فاطّلع على دليلنا الذي يستغرق نحو 10 دقائق حول الانتقال من Travis.

إجراءات CI الخاصة بالمسار

الإجراءات الموصى بها للتحقق من سلامة محتوى مستودعك هي كما يلي:

  1. فحص configlet للتحقق من config.json
  2. التحقق من العناصر الناقصة
  3. التحقق من التوثيق (v3 يتطلب ملفات جديدة؛ قد ينتقل هذا إلى configlet)
  4. فحص التمارين باستخدام إعداد "maintainers"
  5. اختبار التمارين باستخدام ملفات المثال/النموذج (قد تتضمن خطوة بناء)

قد تكون هناك أيضًا إجراءات خاصة بالمسار. على سبيل المثال:

  1. التحقق من السلامة لإعدادات التمارين
  2. التحقق من تنسيق ملفات التمارين

وربما تريد مزيدًا من الفحوصات التي تحسّن جودة الحياة، مثل:

  1. التأكد من وجود CONTRIBUTING
  2. التأكد من وجود ملف قفل معقول للاعتماديات
  3. التأكد من صلاحية الروابط داخل ملفات markdown
  4. ...

التوصيات

وتيرة تشغيل الفحوصات

فكّر لكل إجراء في عدد المرات التي ينبغي أن يُشغَّل فيها.

  • فحص configlet مهم جدًا (لأن المسار قد يتعطل إذا تعطّل config.json)، لذا يُرجّح أن يعمل دائمًا، لكنه يحتاج إلى العمل مرة واحدة فقط لكل commit.
  • وجود الملفات أو سلامتها يحتاج إلى العمل مرة واحدة فقط لكل commit.
  • إذا كان من المفترض أن يعمل مسار ما تحت إصدارات متعددة من بيئة التشغيل أو من المترجم، فينبغي تشغيل بناء/اختبار التمارين مقابل كل إصدار مدعوم.
  • من المحتمل أن تكون طلبات السحب (PRs) بحاجة إلى تشغيل الإجراءات على الملفات المضافة أو المعدّلة فقط، ولكن بما أن الملف الواحد قد يؤثر على تمرين كامل، فمن الأكثر أمانًا تشغيل الإجراءات على التمرين إذا تغيّر أحد ملفاته.

قد يكون من المفيد جدًا جعل الإجراءات التي ينبغي تشغيلها متاحة محليًا أيضًا. هذا يعني أن النصوص البرمجية التي تقوم بالعمل الفعلي يمكن تشغيلها يدويًا أيضًا. ولتحقيق ذلك، لا تُضمّن الإجراء داخل ملفات سير العمل، بل أنشئ نصًا برمجيًا مستقلًا. على سبيل المثال، يمكن كتابة فحص العناصر الناقصة بالكامل داخل ملف سير العمل، لكن التوصية هنا هي إنشاء نص تنفيذي جديد scripts/ci-check بدلًا من ذلك.

"لكن الأمر قصير جدًا، مثل eslint . --ext ts --ext tsx".

عندما يحتاج هذا الأمر إلى التحديث، يصبح بحاجة إلى التحديث في كل مكان في التوثيق، وفي ملفات سير العمل، وفي أذهان المشرفين. واستخراج هذا إلى نص برمجي يحل كل ذلك. كما أن قراءة ملف سير العمل قد تكون مرهبة جدًا.

الفحوصات على طلبات السحب التي تتغير فيها التمارين

يُشغَّل النصان scripts/pr وscripts/pr-check (انظر القوالب) بوسائط متعددة، واحد لكل ملف تغيّر أو أُضيف في طلب السحب هذا. على سبيل المثال، إذا حُدّث two-fer، فقد تبدو الاستدعاء بهذا الشكل:

scripts/pr exercises/two-fer/README.md exercises/two-fer/.meta/example.ext

يُنصح بتشغيل أي إجراءات على التمرين المتغيّر وليس على الملف المتغيّر. لأن تغيير ملف واحد من المرجح أن يستدعي تغييرات للتمرين بأكمله (فكّر في: الإعدادات والحزم).

لست مستعدًا؟ / معقّد؟

قبل تنفيذ هذا التحسين، يمكن تجاهله بأمان! ويلمّح دليل الانتقال إلى إضافته في مرحلة لاحقة. وإذا جرى تجاهل الوسائط المُدخلة، ستعمل كل الفحوصات على كل التمارين. وهذا جيد تمامًا. سيستغرق الأمر وقتًا أطول فقط.

فحوصات السلامة

إذا كان للمسار ملف اعتماديات واحد "على المستوى الأعلى" و/أو ملفات إعدادات أخرى، فأضف خطوة سلامة (توجد إلى جانب scripts/sync أو bin/sync، الذي ينسخ كل ملفات الإعدادات إلى جميع التمارين)، تضمن أن الملفات الأساسية/العليا مماثلة لتلك المنسوخة إلى مجلدات التمارين. وهكذا يمكن تحديث الاعتماديات ومزامنتها عبر المستودع، ويمكننا التأكد من أن جميع التمارين لديها الإعدادات نفسها.

ومن الطرق الشائعة لتحقيق ذلك استخدام قيمة تحقق. يأتي Ubuntu (وتوزيعات لينكس أخرى متنوعة) بأداة تُدعى sha1sum، لكن استخدام أيٍّ كان من الطرق لتجزئة ملف الإعدادات أو اختزاله (md5 أو sha1 أو crc32) إلى قيمة تحقق سينجح:

$ sha1sum README.md
cd58091c5043bf21f00d39ff1740d8b2976deeff *README.md

فحوصات الأمان

إذا كان المسار يستخدم سير عمل إضافية تتطلب الوصول إلى رمز GitHub أو أسرار أخرى، فمن أفضل الممارسات تثبيت كل الإجراءات المستخدمة في سير العمل على commit معيّن. راجع دليل GitHub لتقوية الأمان للتفاصيل.

على سبيل المثال:

- uses: julia-actions/setup-julia@v1
+ uses: julia-actions/setup-julia@d26d1111976eae5f00db04f0515ab744ec9cd79e # 1.3.1

وإذا كانت أدواتك تستخدم ملفات قفل لإدارة الاعتماديات، ففكّر في إضافتها إلى المستودع واستخدام "ملف قفل مجمّد" داخل ملفات سير العمل. على سبيل المثال: npm ci وyarn install --frozen-lockfile وbundle install --frozen. هذا يضمن أن ملف القفل محدّث عند تغيير الاعتماديات ويمنع دخول الحزم الضارة.

القوالب

في هذا المجلد توجد على الأقل القوالب التالية:

  • configlet.yml: سيجلب سير العمل هذا أحدث ملف ثنائي لـ configlet ويفحص هذا المستودع. يعمل على كل commit. أما طلبات السحب، فيعمل على الـ commit الفعلي وعلى شجرة "بعد الدمج".
  • ci.yml: سير العمل هذا يعمل على الفرع الرئيسي فقط، مرة واحدة على كل commit.
    1. تشغيل أمر 'pre-check' (التحقق من العناصر الناقصة، والفحص، والتوثيق، وما إلى ذلك) لكل التمارين
    2. تشغيل أمر 'ci' (البناء والاختبار) لإصدارات متعددة، لكل التمارين
  • pr.ci.yml: سير العمل هذا يعمل على طلبات السحب فقط، مرة واحدة على كل commit.
    1. تشغيل أمر 'pre-check' (التحقق من العناصر الناقصة، والفحص، والتوثيق، وما إلى ذلك) للملفات المتغيّرة
    2. تشغيل أمر 'ci' (البناء والاختبار) لإصدارات متعددة، للتمارين المتغيّرة

ويمكن أيضًا تشغيل سير العمل غير الخاص بطلبات السحب عبر workflow_dispatch.

يسرد كل ملف في أعلاه النصوص البرمجية التي ينبغي أن تكون متاحة. وإذا أردتها أن تكون ملفات ثنائية، فاستبدل scripts/xxx بـ bin/xxx. وبعض الأدوات تتطلب أن تكون الملفات الثنائية داخل مجلد bin.

  • scripts/ci: نص برمجي ينبغي أن يبني ويختبر كل التمارين باستخدام الحلول النموذجية مقابل الاختبارات
  • scripts/ci-check: نص برمجي ينبغي أن يفحص كل التمارين، واختياريًا التحقق من العناصر الناقصة وسلامة الإعدادات والمزيد
  • scripts/pr: مثل scripts/ci، لكنه يجب أن يشغّل فقط التمارين المستخرجة من المسارات المعطاة كمدخلات
  • scripts/pr-check: مثل scripts/ci-check، لكنه يجب أن يعمل فقط على الملفات أو التمارين المستخرجة من المسارات المعطاة كمدخلات

استكشاف الأخطاء وإصلاحها

إذا واجهت أي مشكلات أو أردت أن يراجع أحدهم سير عملك، فنرجو إبلاغ فريق @exercism/github-actions.

غيّرت ملفًا على المستوى الأعلى ينبغي أن يستدعي تشغيل CI على كل التمارين

في وقت كتابة هذا، يسمح pr.ci.yml باختبار "الامتداد" فقط. ومن الناحية المثالية، يُحدَّث هذا ليُشغَّل دائمًا عند تغيّر ملفات معيّنة (على سبيل المثال الملف الثنائي لتنفيذ الاختبارات). لكن هذه التغييرات غالبًا ما تكون نادرة ويقوم بها المشرفون، لذا فكون ci.yml يعمل على الفرع الرئيسي، دائمًا، ولكل شيء، آمن بما يكفي على الأرجح.

أنشأت ملف scripts/xxx على Windows والآن لا يعمل على {other OS}

بشكل افتراضي، لا تتضمن الملفات المنشأة على Windows بيانات وصفية في فهرس git حول قابليتها للتنفيذ، لأن نموذج الأذونات على Windows مختلف. وسيستخدم Git، بشكل افتراضي، البيانات الوصفية في فهرس git لتحديد ما إذا كان ينبغي أن يكون الملف قابلًا للتنفيذ على الأنظمة المبنية على POSIX، وبالتالي يجعل ملف scripts/xxx غير قابل للتنفيذ.

git update-index --chmod=+x scripts/xxx
git commit -m "Make scripts/xxx executable"