الانتقال إلى المحتوى الرئيسي
عندما ترسل طلب سحب، يُجري نظام التكامل المستمر (CI) في ClickHouse بعض الفحوصات المؤتمتة على تعليماتك البرمجية. ويحدث ذلك بعد أن يراجع أحد مسؤولي صيانة المستودع (شخص من فريق ClickHouse) تعليماتك البرمجية ويضيف الوسم can be tested إلى طلب السحب الخاص بك. تُدرَج نتائج هذه الفحوصات في صفحة طلب السحب على GitHub، كما هو موضح في وثائق GitHub الخاصة بفحوصات الحالة. إذا أخفق أحد الفحوصات، فقد يُطلب منك إصلاحه. تقدم هذه الصفحة نظرة عامة على الفحوصات التي قد تواجهها، وما يمكنك فعله لإصلاحها. إذا بدا أن إخفاق الفحص غير مرتبط بتغييراتك، فقد يكون ذلك إخفاقًا عابرًا أو مشكلة في البنية التحتية. أرسل commit فارغًا إلى طلب السحب لإعادة تشغيل فحوصات CI: 
git commit --allow-empty
git push
إذا لم تكن متأكدًا مما ينبغي فعله، فاطلب المساعدة من أحد مشرفي المشروع.

​
الدمج مع master

يتحقق من أن طلب السحب يمكن دمجه في master. إذا لم يكن ذلك ممكنًا، فسيفشل مع الرسالة Cannot fetch mergecommit. لإصلاح هذا التحقق، حلّ التعارض كما هو موضح في وثائق GitHub، أو ادمج الفرع master في فرع طلب السحب باستخدام git.

​
فحص الوثائق

يحاول بناء موقع وثائق ClickHouse. قد يفشل إذا أجريتَ تغييرًا في الوثائق. والسبب الأرجح هو وجود رابط مرجعي داخلي غير صحيح في الوثائق. انتقل إلى تقرير الفحص وابحث عن رسائل ERROR وWARNING.

​
التحقق من الوصف

تحقق من أن وصف طلب السحب الخاص بك يتوافق مع القالب PULL_REQUEST_TEMPLATE.md. يجب عليك تحديد فئة في سجل التغييرات للتغيير الذي أجريته (على سبيل المثال، Bug Fix)، وكتابة رسالة واضحة للمستخدم تصف هذا التغيير من أجل CHANGELOG.md

​
صورة Docker

يبني صور Docker الخاصة بخادم ClickHouse وKeeper للتحقق من بنائها بشكل صحيح.

​
اختبارات مكتبة Docker الرسمية

يُشغِّل اختبارات مكتبة Docker الرسمية للتحقق من أن صورة Docker ‏clickhouse/clickhouse-server تعمل على النحو الصحيح. لإضافة اختبارات جديدة، أنشئ دليلاً ci/jobs/scripts/docker_server/tests/$test_name وأضِف إليه البرنامج النصي run.sh. يمكن العثور على تفاصيل إضافية حول الاختبارات في توثيق البرامج النصية لمهام CI.

​
فحص Marker

يعني هذا الفحص أن نظام CI قد بدأ معالجة طلب السحب. وعندما تكون حالته ‘pending’، فهذا يعني أن بعض الفحوصات لم تبدأ بعد. وبعد بدء جميع الفحوصات، تتغير حالته إلى ‘success’.

​
Style check

يُجري فحوصات متنوعة للأسلوب على قاعدة الشيفرة. ويتوافق كل فحص فرعي أدناه مع testname في ci/jobs/check_style.py، ويمكن تشغيل كلٍّ منها على حدة باستخدام --test <name> (انظر أدناه).
cpp
فحوصات نمط C++ المستندة إلى Regex عبر check_cpp.sh. إذا فشل، فأصلِح المشكلات وفقًا لـدليل نمط الشيفرة.
whitespace_check
يرصد المسافات المزدوجة بعد الفواصل في ++C إذا لم تكن جزءًا من محاذاة الأعمدة.
catch_all
يمنع استخدام catch (...) خارج المدمِّرات وmain ونقاط دخول fuzzer، إذ إن تجاهل استثناء غير معروف ليس آمنًا.
yamllint
يدقّق ملفات سير العمل بتنسيق YAML ضمن .github/ باستخدام .yamllint.
xmllint
يتحقق من صحة ملفات XML في tests/ وprograms/.
functional_tests_check
يفحص الاختبارات عديمة الحالة: يجب أن تستخدم الاستعلامات التي تُطبِّق عامل تصفية على event_date ‎>= yesterday() بدلاً من today() (لتجنّب التذبذب حول منتصف الليل)، ويجب ألا تتضمن أسماء ملفات الاختبار fail.
test_numbers_check
يرصد فجوات كبيرة في ترقيم الاختبارات عديمة الحالة (tests/queries/0_stateless/<NNNNN>_*). يكشف عن الروابط الرمزية المعطّلة في المستودع.
متفرقات
فحوصات متنوعة للمستودع عبر various_checks.sh: يجب أن تستخدم الاستعلامات على system.query_log / system.parts / إلخ عامل تصفية حسب currentDatabase، ويجب أن تتضمن مسارات ZooKeeper الخاصة بـ Replicated*MergeTree بادئةً خاصة بكل اختبار، ويجب أن تحتوي أدلة اختبارات التكامل على __init__.py، وألا توجد علامات UTF BOM، وألا تكون ملفات المصدر/البيانات مفعّلًا عليها بتات التنفيذ، وألا تُستخدم وسوم :latest مع صور docker-compose التابعة لجهات خارجية، وغير ذلك.

​
تشغيل مهمة Style Check محليًا

يمكن تشغيل مهمة Style Check بالكامل محليًا داخل حاوية Docker باستخدام: 
python -m ci.praktika run "Style check"
لتشغيل فحص معيّن (مثل فحص cpp): 
python -m ci.praktika run "Style check" --test cpp
تسحب هذه الأوامر صورة Docker ‏clickhouse/style-test وتشغّل المهمة ضمن بيئة حاويات. لا يلزم أي تبعيات أخرى سوى بايثون 3 وDocker.

​
تشغيل الاختبارات عديمة الحالة

قد يعمل ClickHouse المثبّت محليًا بإعداداته الافتراضية مع بعض حالات الاختبار، لكنه لا يستطيع تشغيل جميع استعلامات الاختبار بشكل صحيح. في CI، تُثبّت كل مهمة إعدادًا محددًا لـ ClickHouse (مثل تخزين S3 والنسخ المتماثلة المتوازية)، وقد يكون من الصعب إعادة ذلك يدويًا. لتجنّب ذلك، يمكنك إعادة تنفيذ أي مهمة CI محليًا باستخدام آلية التنسيق نفسها المستخدمة في CI، من دون الحاجة إلى أي إعداد يدوي.

​
المتطلبات الأساسية

  • بايثون 3 (المكتبة القياسية فقط)
  • Docker
ثبّت Docker على Ubuntu إذا لزم الأمر، ثم أعِد تسجيل الدخول: 
sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker "$USER"
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "ip6tables": true
}
EOF
sudo systemctl restart docker

​
تشغيل مهمة CI محليًا

اختر أي اسم مهمة من تقرير CI وشغّلها محليًا: 
python -m ci.praktika run "<JOB_NAME>"
  • احرص دائمًا على وضع اسم الـ مهمة بين علامتَي اقتباس تمامًا كما يظهر في تقرير CI (إذ قد يحتوي على مسافات وفواصل)، مثل: "Stateless tests (amd_debug, parallel)". يضبط ذلك إعدادات ClickHouse نفسها ويشغّل الاختبارات نفسها المستخدمة في CI.
  • إن المعمارية ونوع البناء في اسم الـ مهمة (مثل amd_debug) هما تسميتان خاصتان بـ CI. وعند التشغيل محليًا، لا يكون لهما أي تأثير — إذ سيستخدم الـ مهمة أي ملف تنفيذي توفّره وعلى أي معمارية تعمل. يحدّد اسم الـ مهمة فقط إعدادات ClickHouse ومجموعة الاختبارات (ما لم يتم تجاوز ذلك باستخدام --test).
  • في CI، تُقسَّم الاختبارات الوظيفية إلى دفعات لتحسين استخدام الموارد. على سبيل المثال، يغطي كلٌّ من "Stateless tests (amd_debug, parallel)" و"Stateless tests (amd_debug, sequential)" النطاق الكامل معًا: تُشغَّل الاختبارات الآمنة للتوازي بشكل متزامن، بينما تُشغَّل بقية الاختبارات بشكل تسلسلي. ويقلّل هذا التقسيم الوقت الإجمالي في CI من خلال زيادة التوازي إلى أقصى حد ممكن. ولإعادة تنفيذ نطاق الاختبار الكامل محليًا، شغّل كلتا الدفعتين.
  • توجد أيضًا مهمة في CI باسم "Fast test" تشغّل نطاقًا محدودًا من الاختبارات الوظيفية للتحقق من الوظائف الأساسية في ClickHouse — وهي تستخدم build لا يتضمن جميع الوحدات الاختيارية، وتُعد أسرع طريقة لاكتشاف حالات التراجع. يمكنك تشغيلها محليًا بالطريقة نفسها. ضع ملف ClickHouse التنفيذي في أحد مسارات البحث الافتراضية (./ci/tmp/clickhouse, ./build/programs/clickhouse, أو ./clickhouse) — وإلا فستحاول الـ مهمة بناء ClickHouse أولًا: 
    python -m ci.praktika run "Fast test"

​
تشغيل اختبارات محددة ضمن مهمة CI

باستخدام --test، تُعِدّ المهمة بيئة ClickHouse مطابقة لتلك المستخدمة في CI، لكنها تُشغِّل الاختبارات المحددة فقط: 
python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1
  • يمكنك تمرير أسماء اختبارات متعددة: 
    python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting
  • نصيحة: إذا كان أي إعداد لـ ClickHouse مناسبًا وكنت تحتاج فقط إلى تشغيل اختبارات معيّنة، فاستخدم الاسم البديل functional بدلًا من اسم المهمة الكامل: 
    python -m ci.praktika run functional --test 00001_select1

​
خيارات تخصيص إضافية

  • --path PATH — مسار مخصّص لملف ClickHouse التنفيذي. افتراضيًا، يبحث المشغّل بالترتيب التالي: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
  • --count N — كرّر كل اختبار N مرة.
  • --workers N — تجاوز الحساب التلقائي لعدد العمّال المتوازيين المستند إلى سعة الجهاز.

​
التحقق من البناء

يبني ClickHouse ضمن تهيئات مختلفة لاستخدامه في الخطوات اللاحقة.

​
تشغيل عمليات البناء محليًا

يمكن تشغيل عملية البناء محليًا في بيئة مشابهة لبيئة CI باستخدام: 
python -m ci.praktika run "<BUILD_JOB_NAME>"
لا يلزم أي تبعيات أخرى سوى بايثون 3 وDocker.

​
مهام البناء المتاحة

أسماء مهام البناء هي نفسها تمامًا كما تظهر في تقرير CI: عمليات بناء AMD64:
  • Build (amd_debug) - بنية Debug مع الرموز
  • Build (amd_release) - بنية إصدار محسّنة
  • Build (amd_asan) - بنية Address Sanitizer
  • Build (amd_tsan) - بنية Thread Sanitizer
  • Build (amd_msan) - بنية Memory Sanitizer
  • Build (amd_ubsan) - بنية Undefined Behavior Sanitizer
  • Build (amd_binary) - بنية إصدار سريعة بدون Thin LTO
  • Build (amd_compat) - بنية توافق للأنظمة الأقدم
  • Build (amd_musl) - بنية باستخدام musl libc
  • Build (amd_darwin) - بنية macOS
  • Build (amd_freebsd) - بنية FreeBSD
عمليات بناء ARM64:
  • Build (arm_release) - بنية إصدار ARM64 محسّنة
  • Build (arm_asan) - بنية ARM64 لـ Address Sanitizer
  • Build (arm_coverage) - بنية ARM64 مع تضمين أدوات قياس التغطية
  • Build (arm_binary) - بنية إصدار ARM64 سريعة بدون Thin LTO
  • Build (arm_darwin) - بنية macOS لـ ARM64
  • Build (arm_v80compat) - بنية توافق ARMv8.0
معماريات أخرى:
  • Build (ppc64le) - PowerPC ‏64-بت بنظام Little Endian
  • Build (riscv64) - RISC-V ‏64-بت
  • Build (s390x) - IBM System/390 ‏64-بت
  • Build (loongarch64) - LoongArch ‏64-بت
إذا نجحت المهمة، فستتوفر نتائج البناء في الدليل <repo_root>/ci/tmp/build. ملاحظة: بالنسبة إلى عمليات البناء التي لا تندرج ضمن فئة “معماريات أخرى” (والتي تستخدم التجميع المتقاطع)، يجب أن تتطابق معمارية جهازك المحلي مع نوع البناء لإنتاج البنية المطلوبة بواسطة BUILD_JOB_NAME.

​
مثال

لتشغيل نسخة تصحيح محلية: 
python -m ci.praktika run "Build (amd_debug)"
إذا لم تنجح الطريقة المذكورة أعلاه معك، فاستخدم خيارات cmake من سجل البناء واتبع عملية البناء العامة.

​
الاختبارات الوظيفية عديمة الحالة

يشغّل الاختبارات الوظيفية عديمة الحالة لملفات ClickHouse التنفيذية المبنية بإعدادات مختلفة — release وdebug ومع أدوات sanitizers وما إلى ذلك. اطّلع على التقرير لمعرفة الاختبارات التي تفشل، ثم أعد إنتاج الفشل محليًا كما هو موضح هنا. لاحظ أنه يجب استخدام إعداد البناء الصحيح لإعادة الإنتاج — فقد يفشل اختبار عند استخدام AddressSanitizer لكنه ينجح في Debug. نزّل الملف التنفيذي من صفحة فحوصات بناء CI، أو ابنِه محليًا.

​
اختبارات التكامل

يشغّل اختبارات التكامل.

​
فحص التحقق من إصلاح الأخطاء

يتحقق من وجود اختبار جديد (وظيفي أو تكاملي)، أو من وجود اختبارات معدّلة تفشل عند استخدام الملف التنفيذي المبني من فرع master. يُفعَّل هذا الفحص عندما يكون طلب السحب موسومًا بالوسم “pr-bugfix”.

​
اختبار الإجهاد

يشغّل الاختبارات الوظيفية عديمة الحالة بالتوازي من عدة عملاء لاكتشاف الأخطاء المرتبطة بالتزامن. إذا أخفق:
  • أصلح أولاً جميع حالات فشل الاختبارات الأخرى؛
    • راجع التقرير للعثور على سجلات الخادم وتحقق منها بحثًا عن الأسباب المحتملة للخطأ.

​
التحقّق من التوافق

يتحقّق من أنّ الملف التنفيذي clickhouse يعمل على التوزيعات التي تستخدم إصدارات قديمة من libc. إذا فشل، فاطلب المساعدة من أحد مسؤولي الصيانة.

​
AST fuzzer

يشغّل استعلامات مُولَّدة عشوائيًا لاكتشاف أخطاء في البرنامج. إذا تعذّر عمله، فاطلب المساعدة من أحد مسؤولي الصيانة.

​
اختبارات الأداء

لقياس التغيّرات في أداء الاستعلامات. هذا هو أطول فحص، ويستغرق تشغيله أقل بقليل من 6 ساعات. يُوضَّح تقرير اختبار الأداء بالتفصيل هنا.
آخر تعديل في ٢٥ يونيو ٢٠٢٦