دليل طرح التغييرات المعطّلة

ومن الطبيعي أن نُجري تغييرات قد تؤدي إلى أعطال في Bazel. وبالتالي، علينا تغيير تصاميمنا وإصلاح العناصر التي لا تعمل بشكل جيد. ومع ذلك، يجب أن نتأكد من أنّ منظومة Bazel المتكاملة والمتّبعة في المجال متوافقة مع هذه المتطلبات. ولتحقيق هذه الغاية، التزمت شركة Bazel بسياسة التوافق مع الأنظمة القديمة. يوضّح هذا المستند طريقة إجراء التغييرات التي قد يتّخذها المساهمون في Bazel في ما يتعلق بهذه السياسة من أجل الالتزام بهذه السياسة.

1. اتّبِع سياسة مستند التصميم.

2. الإبلاغ عن مشكلة على GitHub

3. ادخل التغيير.

4. تعديل التصنيفات

5. اقلب العلامة غير المتوافقة.

مشكلة GitHub

الإبلاغ عن مشكلة GitHub في مستودع Bazel اطّلِع على المثال.

ننصحك بما يلي:

• يبدأ العنوان باسم العلامة (يبدأ اسم العلامة بـ incompatible_).

• ويمكنك إضافة التصنيف incompatible-change.

• يتضمن الوصف وصفًا للتغيير ورابطًا إلى مستندات التصميم ذات الصلة.

• يتضمّن الوصف وصفة لنقل البيانات توضّح للمستخدمين كيفية تعديل رمزهم. في العادة، عندما يكون التغيير ميكانيكيًا، يمكنك تضمين رابط إلى أداة نقل البيانات.

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

بالنسبة إلى أداة نقل البيانات، يمكنك المساهمة في Buildifier. ويمكنه تطبيق الإصلاحات المبرمَجة على الملفات BUILD وWORKSPACE و.bzl. وقد يتم أيضًا الإبلاغ عن التحذيرات.

التنفيذ

إنشاء علامة جديدة في Bazel ويجب أن تكون القيمة التلقائية خطأ. يجب أن يحتوي نص المساعدة على عنوان URL لمشكلة GitHub. يجب إضافة علامات البيانات الوصفية لأنّ اسم العلامة يبدأ بـ incompatible_.

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

في وصف الإتمام، أضِف ملخّصًا موجزًا عن العلامة. أضِف RELNOTES: أيضًا على النحو التالي: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

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

التصنيفات

بعد دمج التنفيذ والاستعداد للتغيير غير المتوافق، أضِف التصنيف migration-ready إلى مشكلة GitHub.

إذا تم العثور على مشكلة في العلامة ولم يكن من المتوقّع أن يُنقل المستخدمون بعد: يمكنك إزالة العلامات migration-ready.

إذا كنت تريد قلب العلامة في الإصدار الرئيسي التالي، أضِف التصنيف "breaking-change-X.0&quot إلى المشكلة.

جارٍ تحديث المستودعات

تختبر Bazel CI قائمة بالمشروعات المهمّة على العنوان Bazel@HEAD + Workdown. وغالبًا ما يكون معظمها تابعًا لمشاريع Bazel الأخرى، لذا من المهم نقلها لإزالة حظر نقل البيانات على نطاق أوسع.

ولمراقبة حالة نقل بيانات تلك المشاريع، يمكنك استخدام bazelisk-plus-incompatible-flagsمسار التعلّم، يمكنك الاطّلاع على آلية عمل هذا المسار هنا.

لا تقع مسؤولية نقل البيانات ضمن مسار التعلّم بالكامل على نحو كامل. وفي المقابل، يمكنك اتّباع الإجراءات التالية لتسريع عملية نقل البيانات وتسهيل الأمور على كل من مستخدمي Bazel وفريق Bazel Green.

1. قدِّم مشاكل في GitHub لإبلاغ مالكي المشاريع النهائية المعطلة بسبب التغيير غير المتوافق.
2. يمكنك إرسال علاقات عامة لإصلاح المشاريع الأولية.
3. يُرجى التواصل مع منتدى Bazel للحصول على مساعدة بشأن نقل البيانات (مثل Bazel Rules Authors SIG).

القلب المعكوس

قبل تغيير القيمة التلقائية للعلامة إلى "صحيح"، يُرجى التأكد مما يلي:

• يتم نقل بيانات المستودعات الأساسية في المنظومة المتكاملة.

  على خط bazelisk-plus-incompatible-flags، من المفترض أن تظهر العلامة ضمن The following flags didn't break any passing Bazel team owned/co-owned projects.

• الإجابة عن أسئلة المستخدمين ومخاوفهم.

عندما تكون العلامة جاهزة للتغيير في Bazel، ولكن تم حظرها في النقل الداخلي في Google، يُرجى ضبط قيمة العلامة على"خطأ"في ملف blazerc الداخلي لإزالة علامة التبديل. ومن خلال ذلك، يمكننا التأكّد من أنّ مستخدمي Bazel يعتمدون على السلوك الجديد تلقائيًا في أقرب وقت ممكن.

عند تغيير الإعداد التلقائي إلى "صحيح"، يُرجى تنفيذ ما يلي:

• استخدِم RELNOTES[INC] في وصف الإتمام، بالتنسيق التالي: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details يمكنك تضمين معلومات إضافية في باقي وصف الإتمام.
• استخدِم Fixes #xyz في الوصف لكي يتم إغلاق مشكلة GitHub عند دمج الدمج.
• يُرجى مراجعة المستندات وتعديلها إذا لزم الأمر.
• قدِّم مشكلة جديدة #abc لتتبُّع إزالة العلامة.

جارٍ إزالة العلامة

بعد قلب العلامة إلى HEAD، يجب إزالتها من Bazel في النهاية. عندما تخطط لإزالة العلامة غير المتوافقة:

• يمكنك ترك المزيد من الوقت للمستخدمين لنقل البيانات إذا كان التغيير الرئيسي غير متوافق. في العادة، يجب أن تتوفّر العلامة في إصدار رئيسي واحد على الأقل.
• بالنسبة إلى الكيان الذي يزيل العلامة، استخدِم Fixes #abc في الوصف لكي يتم إغلاق مشكلة GitHub عند دمج الاقتراح.