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

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

:mag: نظرة عامة

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

يعد إعداد سير عمل \u003cabbr title="التكامل المستمر"\u003eCI\u003c/abbr\u003e باستخدام GitHub Actions لأتمتة عمليات البناء والاختبار هو النهج الذي يستخدمه فريق Discourse في جميع مكوناتنا، ونوصي بأن تفعل الشيء نفسه.

:gear: الإعداد

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

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

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

في مستودع الهيكل الخاص بالقالب، يمكنك النقر على زر \u003ckbd\u003eاستخدام هذا القالب\u003c/kbd\u003e على GitHub لإنشاء مستودع مكون إضافي/مكون سمة بناءً على القالب.

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

:electric_plug: المكونات الإضافية (Plugins): discourse-plugin.yml

:jigsaw: السمات ومكونات السمة (Themes and Theme Components): discourse-theme.yml

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

:tada: فويلا! لقد انتهيت من الإعداد! ببساطة، قم بإنشاء التزام (commit) أو \u003cabbr title="طلب سحب"\u003ePR\u003c/abbr\u003e إلى المستودع الخاص بك وستكتشف إجراءات GitHub سير العمل تلقائيًا وتبدأ في تشغيل المهام.

ستعرض إجراءات GitHub تفصيلاً لكل اختبار وبعد التشغيل ستشير إما إلى :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: عرض المجلد

\u003csmall\u003eهذا المستند يتم التحكم في إصداره - اقترح تغييرات على github.\u003c/small\u003e

\u003c!-- START DOCS ASSET MAP
[
{
"local_path": "/assets/ci-with-github-actions-1.png",
"local_sha1": "c3fb59eeb13645670b751959d13cdf8e423e0fcf",
"remote_short_url": "upload://imziUfvg1AloA7IQ5jXMyn85Ngu.png"
}
]
END DOCS ASSET MAP –\u003e

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)