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

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

:mag: نظرة عامة

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

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

:gear: الإعداد

لإضافة سير عمل آلي لـ GitHub actions للكشف، تحتاج إلى إنشاء مجلد .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 250 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)