إعداد التكامل المستمر باستخدام GitHub Actions

توثيق أدلة المطور
,
1

:mag: نظرة عامة

لبناء إضافة قوية لـ Discourse، قد يكون من الحكمة تضمين التكامل المستمر (CI) في إضافة أو مكوّن القالب الخاص بك. سيساعد هذا في اكتشاف الأخطاء مبكرًا ويقلل من احتمالية وجود أخطاء برمجية في الكود.

إعداد سير عمل CI باستخدام GitHub Actions لأتمتة عمليات البناء والاختبار هو نهج يتبعه فريق Discourse في جميع مكوناتنا، ونوصيكم بالقيام بالمثل.

:gear: الإعداد

لإضافة سير عمل آلي لأفعال GitHub للكشف عن الأخطاء، تحتاج إلى إنشاء مجلد .github/workflows في المجلد الجذري (root) لمستودعك.

داخل مجلد workflows يمكنك تحديد مجموعة من الأتمتات التي ستحتاج GitHub Actions إلى تشغيلها. على سبيل المثال، قد تكون هذه ملفات .yml للفحص (linting) والاختبارات.

لقد أنشأنا سير عمل قوالب لكل من الإضافات ومكونات القوالب والتي يمكنك الاستفادة منها. ترتبط هذه التعريفات بتعريفات “سير العمل القابلة لإعادة الاستخدام” الخاصة بنا هنا.

في مستودع الهيكل (skeleton) للقالب، على GitHub يمكنك النقر على زر Use this template لإنشاء مستودع إضافة/مكوّن قالب بناءً على القالب.

بديلًا عن ذلك، إذا كان لديك مشروع بالفعل وتريد إضافة سير العمل إليه، ما عليك سوى نسخ سير العمل ذي الصلة إلى مجلد .github/workflows/ في مستودعك:

:electric_plug: الإضافات: discourse-plugin.yml

:jigsaw: القوالب ومكونات القوالب: discourse-theme.yml

:point_up: هذه القوالب مقفلة على إصدار رئيسي (major version) محدد من سير العمل القابلة لإعادة الاستخدام لدينا. التحسينات الصغيرة التي نجريها على سير العمل ستدخل حيز التنفيذ تلقائيًا في قالبك/إضافتك. بالنسبة للتغييرات التي تكسر التوافق (مثل إدخال أداة فحص جديدة)، سنقوم بترقية الإصدار الرئيسي لسير العمل القابلة لإعادة الاستخدام، وستحتاج إلى تحديث سير عملك للإشارة إلى الإصدار الجديد.

:tada: ها قد أُنجز! ببساطة، أنشئ التزامًا (commit) أو طلب سحب (PR) إلى مستودعك، وستكتشف GitHub Actions سير العمل تلقائيًا وتبدأ بتشغيل المهام.

ستعرض GitHub Actions تفصيلًا لكل اختبار، وبعد تشغيله ستشير إما إلى :white_check_mark: أو :x: اعتمادًا على نجاح الاختبار أو فشله.

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

شاهد مثالًا

example failure
example failure2192×1018 71.8 KB

:white_check_mark: أضف اختباراتك الخاصة

لكي تعمل اختبارات الإضافات والمكونات بفعالية، من المهم أن تكتب اختبارات لإضافتك أو مكوّن القالب الخاص بك.

للتفاصيل حول كيفية كتابة اختبارات الواجهة الأمامية باستخدام EmberJS، راجع:

لمزيد من التفاصيل حول كتابة اختبارات RSpec مع Rails، راجع:

:bulb: أمثلة

لصالحك، اخترنا بعض الأمثلة لإضافات ومكونات قوالب لديها اختبارات قوية متكاملة:

الإضافة / المكوّن اختبارات جانب العميل اختبارات جانب الخادم
Assign :link: عرض المجلد :link: عرض المجلد
Calendar :link: عرض المجلد :link: عرض المجلد
Reactions :link: عرض المجلد :link: عرض المجلد
Right Sidebar Blocks :link: عرض المجلد
Tag Icons :link: عرض المجلد
Table Builder :link: عرض المجلد

هذا المستند مُدار بالإصدارات - اقترح تغييرات على github.

15 إعجابًا
How could a CI workflow for unofficial plugins be implemented?
Unexpected error in Discourse Plugin CI
6

قد تذكر GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes صراحةً وتلاحظ أنه يجب عليك مراقبته لتدوين التغييرات في تلك الملفات.

4 إعجابات
7

نأمل أن يتم دمج سير العمل القابل لإعادة الاستخدام، مما يجعل هذا الجزء أقل أهمية حيث ستستخدم المستودعات الجديدة التي تم إنشاؤها من القالب سير العمل مباشرة من مستودع القالب.

إعجابَين (2)
8

شكراً @pfaffman و @Simon_Manning، نقاط جيدة. لقد قمت بتحديث المنشور الأصلي وفقًا لذلك.

4 إعجابات
9

لقد قمت بتحديث OP لتضمين تعليمات لاستخدام “سير العمل القابل لإعادة الاستخدام” الجديد لدينا. يمكن الآن تطبيق التعديلات الطفيفة التي نجريها على تعريفات سير العمل تلقائيًا على السمات/المكونات الإضافية الخاصة بك دون أي عمل يدوي.

3 إعجابات
10

هل أحتاج إلى القيام بأي شيء خاص لاختبار الإضافة ضد أحدث الاختبارات المارة و المستقرة؟

إعجاب واحد (1)
11

يستخدم سير عمل هيكل المكون الإضافي ما يلي، والذي أعتقد أنه سيختبر مقابل الفرع الافتراضي، لذا main. يحتوي سير العمل القابل لإعادة الاستخدام على إدخال اختياري core_ref وبقدر ما أستطيع أن أقول، بدونه سيتم سحب الفرع الافتراضي لمستودع discourse/discourse.

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

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

jobs:
  ci:
    strategy:
      matrix:
        target: [tests-passed, stable]
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: ${{ matrix.target }}
3 إعجابات
12

نعم، هذا يجب أن يفي بالغرض. أو يمكنك ببساطة كتابة المهمتين يدويًا دون استخدام مصفوفة:

name: Discourse Plugin

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

  ci-stable:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: stable

تجدر الإشارة إلى أن هذه المهام لن تتحقق من .discourse-compatiblity. لذا، فإن هذا يستحق القيام به فقط على المكونات الإضافية التي لا تستخدم هذا الملف، وتحتاج إلى أن تكون متوافقة مع كل من main و stable في نفس الوقت.

بالنسبة لجميع السمات/المكونات الإضافية العامة لـ CDCK، نضيف إدخالًا إلى discourse-compatibility “لتجميدها” عند كل إصدار مستقر. بعد ذلك، لا نحتاج إلى القلق بشأن التوافق المستقر أثناء تطويرها.

5 إعجابات
13

شكرا لكما.

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

إعجابَين (2)