دليل المطوّر إلى Backport Builder

لمحة سريعة

⁨Backport Builder⁩ مشروع لهندسة الإصدارات. تعامل مع مستودعات المصدر بوصفها مدخلات، ومع الأشجار المُولَّدة بوصفها مخرجات، ومع قواعد ⁨Rector⁩ المخصّصة بوصفها منطق بناء مختبَرًا.

استخدم هذا الدليل عند صيانة قواعد الخفض، أو البيانات الوصفية للحزم المُولَّدة، أو فحوص بيئة التشغيل الهدف، أو أتمتة إصدارات nextpdf/backport-builder.

حدّ البنية المعمارية

الطبقة	يملكها	المسؤولية	لا تضع هنا
مستودعات المصدر	مستودعات المنتج	مصدر ⁨PHP⁩ الموثوق واختباراته.	تعديلات الخفض المُولَّدة.
سكربتات البناء	nextpdf/backport-builder	دمج المصدر، وتشغيل التحويلات، وكتابة البيانات الوصفية، والتحقّق من المخرجات.	منطق التطبيق في وقت التشغيل.
تهيئة ⁨Rector⁩	nextpdf/backport-builder	سياسة الخفض الخاصّة بالهدف.	افتراضات عابرة للأهداف دون اختبارات.
قواعد ⁨Rector⁩ المخصّصة	nextpdf/backport-builder	تحويلات بنيوية خاصّة بالمشروع.	إعادات كتابة واسعة غير مختبَرة.
الحزم المُولَّدة	مخرجات البناء	عناصر قابلة للتثبيت على بيئات التشغيل الأقدم.	تصحيحات يدوية تُعدّ مصدر الحقيقة.

دورة حياة البناء

المرحلة	السلوك	إجراء المطوّر
سحب المصدر	يسحب سير عمل الإصدار مستودعات المصدر عند الوسم الهدف.	أبقِ مراجع المصدر متوائمة بين الحزم.
التحقّق من العقد	ValidateBuildContract::run() يفحص افتراضات البناء.	تعامل مع فشل العقد بوصفه مانعًا للإصدار.
الدمج	MergeSources::run() يجمّع شجرة الحزمة الهدف.	تحقّق من نطاق الهدف قبل تشغيل ⁨Rector.⁩
التحويل	تُخفّض تهيئات ⁨Rector⁩ والقواعد المخصّصة البنيةَ النحوية.	أضف اختبارات تثبيتات لكل تغيير في القواعد.
تعديل ⁨Composer⁩	AdjustComposer يكتب البيانات الوصفية للحزمة المُولَّدة وخرائط الاستبدال.	تحقّق من أسماء الحزم والإصدارات والتراخيص والقيود.
التحقّق من وقت التشغيل	تخضع المخرجات المُولَّدة لفحص البنية النحوية ولاختبارها على إصدارات ⁨PHP⁩ الهدف.	تعامل مع فشل بيئة التشغيل الهدف بوصفه مانعًا للإصدار.
الإصدار	تُرفَق الأرشيفات بالإصدار.	لا تصحّح المخرجات المُولَّدة بوصفها مصدر الحقيقة.

سير عمل المستودع الموصى به

عنصر العمل	مصدر الحقيقة	سياسة المخرجات المُولَّدة
استخدام ميزة ⁨PHP⁩	مستودع المصدر الرئيسي.	تكيّف قواعد الخفض الميزةَ.
قيود الاعتماديات	البيانات الوصفية لـ composer.json المصدر إضافةً إلى سكربت التعديل.	يجب أن يكون composer.json المُولَّد قابلًا لإعادة الإنتاج.
خفض البنية النحوية	تهيئة ⁨Rector⁩ والقواعد المخصّصة.	يجب ألّا يُحرَّر المصدر المُولَّد يدويًا.
دعم وقت التشغيل	الفرع الهدف ومصفوفة ⁨CI.⁩	يجب أن ينجح البناء على ⁨PHP⁩ الهدف.
ملاحظات الإصدار	الوثائق وأتمتة الإصدار.	ينبغي أن تربط العناصر المُولَّدة بإصدار المصدر.

نمط قاعدة ⁨Rector⁩ المخصّصة

ينبغي أن يكون لكل قاعدة مخصّصة غرض محدّد وبيانات وصفية وتغطية تثبيتات.

دالّة القاعدة	الغرض	متطلّب الجودة
getRuleDefinition()	توثّق التحويل لأدوات ⁨Rector.⁩	ضمّن عيّنة ⁨before/after⁩ تطابق الخفض الفعلي.
getNodeTypes()	تحدّ من عقد ⁨AST⁩ التي تفحصها القاعدة.	أبقِ قائمة العقد صغيرة قدر الإمكان.
refactor()	يطبّق التحويل أو يعيد العقدة دون تغيير.	اترك العقد غير ذات الصلة دون تغيير، وبسلوك حتمي.
اختبار التثبيتات	يتحقّق من مخرجات ⁨before/after.⁩	غطِّ أصغر مدخل صالح وحالة تخطٍّ واحدة على الأقل.

<?php

final class ExampleDowngradeRector extends AbstractRector
{
    public function getNodeTypes(): array
    {
        return [SomeNode::class];
    }

    public function refactor(Node $node): ?Node
    {
        if (!$node instanceof SomeNode) {
            return null;
        }

        return $this->rewriteNode($node);
    }
}

نمط أمر البناء

استخدم التشغيل الجاف أثناء التطوير وعند التحقّق من الإصدارات المرشّحة. لا تكتب المخرجات الحقيقية إلّا عندما تكون مراجع المصدر والفرع الهدف معروفين.

composer build:dry
php scripts/build.php --version=2.0.0 --target=php81 --dry-run
php scripts/build.php --version=2.0.0 --target=php74 --no-pro

شغّل التحقّق من الحزمة المُولَّدة على بيئة التشغيل الهدف، وليس على مضيف البناء الحديث فقط.

نقاط التوسيع

نقطة التوسيع	استخدمها من أجل	القيد
ملفات تهيئة ⁨Rector⁩	سياسة الخفض الخاصّة بالهدف.	أبقِ مسارَي ⁨PHP 8.1⁩ و ⁨PHP 7.4⁩ منفصلين.
قواعد ⁨Rector⁩ المخصّصة	تحويلات بنيوية خاصّة بالمشروع.	يجب أن تتضمّن بيانات وصفية واختبارات تثبيتات.
سكربت تعديل ⁨Composer⁩	هوية الحزمة المُولَّدة.	يجب أن يحافظ على ترقيم الإصدارات المتوائم مع ⁨SemVer.⁩
سكربت الدمج	انتقاء مدخل حزمة المصدر وتشكيله.	يجب أن يسجّل جذور المصدر وجذور المخرجات.
سير عمل البناء	تنسيق الإصدار.	يجب أن يتحقّق من المخرجات المُولَّدة على بيئة التشغيل الهدف.

سير عمل التطوير

1. أعِد إنتاج البنية النحوية غير المدعومة في تثبيت بسيط.
2. أضف قاعدة ⁨Rector⁩ مخصّصة أو حدّثها.
3. أضف تثبيتات ⁨before/after⁩ للقاعدة.
4. شغّل البناء الجاف.
5. تحقّق من المخرجات المُولَّدة على بيئة تشغيل ⁨PHP⁩ الهدف.
6. طبّق التغيير المنطقي نفسه على كل فرع هدف دائم عند الحاجة.
7. أبقِ عناصر الإصدار قابلة لإعادة الإنتاج من أوسمة المصدر وسكربتات البناء.

معالجة الإخفاقات

الإخفاق	حيث ينبغي معالجته	الاستجابة الموصى بها
مستودع مصدر مفقود	مرحلة التحقّق من العقد أو الدمج.	أوقف البناء وأصلح مدخلات السحب.
فشل تحليل ⁨Rector⁩	مرحلة التحويل.	اختزِل إلى تثبيت وحدّث القاعدة أو التهيئة.
عدم تطابق composer.json المُولَّد	مرحلة تعديل ⁨Composer.⁩	أصلح سكربت التوليد، لا البيانات الوصفية المُولَّدة.
فشل البنية النحوية للهدف	التحقّق من وقت التشغيل.	امنع الإصدار حتى يُصحَّح التحويل.
مصدر ⁨Pro⁩ غير متاح	تهيئة البناء.	ابنِ العنصر العام فقط عندما يكون ذلك هو الهدف المقصود.

الإعدادات الافتراضية الآمنة

الشاغل	الافتراضي	متى تتجاوزه
المخرجات المُولَّدة	عنصر للقراءة فقط.	لا تجعله أبدًا مصدر الحقيقة.
نموذج الفروع	فروع هدف دائمة منفصلة.	أبقِ التغييرات متزامنة عبر طلبات سحب مستقلة.
مضيف البناء	⁨PHP⁩ حديث.	يظلّ التحقّق من بيئة التشغيل الهدف هو ما يقرّر جاهزية الإصدار.
القواعد المخصّصة	صغيرة ومدعومة بتثبيتات.	تجنّب التحويلات الواسعة دون أمثلة ⁨before/after⁩ صريحة.
مسار ⁨PHP 7.4⁩	النواة فقط ما لم يُدعَم خلاف ذلك صراحةً.	لا تُدرج مخرجات ⁨Pro⁩ دون التحقّق من بيئة التشغيل الهدف.

قائمة تحقّق الاختبار

• تُنشئ اختبارات البيانات الوصفية لقواعد ⁨Rector⁩ نسخةً من كل قاعدة مخصّصة.
• تغطّي اختبارات التثبيتات الكودَ قبل كل تحويل وبعده.
• يُشغَّل البناء الجاف قبل مهام الإصدار.
• تُجرى فحوص البنية النحوية لبيئة التشغيل الهدف واختبارات الحزمة على المخرجات المُولَّدة.
• تؤكّد اختبارات البيانات الوصفية لـ ⁨Composer⁩ اسمَ الحزمة وإصدارها وقيودها وخريطة الاستبدال والترخيص.
• تتضمّن سجلّات البناء مسارات المصدر، ومسار الهدف، وبيئة التشغيل الهدف، وحالة التشغيل الجاف، وحالة تضمين ⁨Pro.⁩