مستندات التصميم

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

في ما يلي بعض الأمثلة على التغييرات المهمة:

  • إضافة قواعد الإصدار الأصلي أو حذفها
  • التغييرات الطفيفة على القواعد الأصلية
  • التغييرات على دلالات القاعدة الأصيلة للبنية والتي تؤثر على سلوك أكثر من قاعدة واحدة
  • تغييرات على واجهة برمجة تطبيقات تعريف قواعد Bazel
  • التغييرات على واجهات برمجة التطبيقات التي يستخدمها Bazel للاتصال بأنظمة أخرى
  • تغييرات على لغة Starlark أو دلالات الألفاظ أو واجهات برمجة التطبيقات
  • التغييرات التي قد يكون لها تأثير مطوّل على أداء Bazel أو استخدام الذاكرة (للأفضل أو الأسوأ)
  • تغييرات على واجهات برمجة التطبيقات الداخلية المستخدمة على نطاق واسع
  • التغييرات على العلامات وواجهة سطر الأوامر.

أسباب مراجعات التصميم

عند كتابة مستند تصميم، يمكنك التنسيق مع مطوّري البرامج الآخرين في Bazel للحصول على إرشادات من فريق Bazel الأساسي. مثلاً، عند إضافة اقتراح أو إزالة أو تعديل أي دالة أو كائن متاح في ملفات BUILD أو WORKSPACE أو bzl، أضِف فريق Starlark كمراجعين. تتم مراجعة مستندات التصميم قبل الإرسال للأسباب التالية:

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

تساعد سياسة مراجعة تصميم Bazel في زيادة احتمالية:

  • تخضع جميع طلبات الميزات لعملية مراجعة دقيقة.
  • وسيركز الأشخاص المناسبين على التصاميم قبل أن نستثمر في عملية تنفيذ قد لا تعمل.

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

سير عمل المساهم

بصفتك مساهمًا، يمكنك كتابة مستند للتصميم وإرسال طلبات السحب وطلب مراجعين لاقتراحك.

كتابة مستند التصميم

يجب أن تحتوي جميع مستندات التصميم على عنوان يتضمن:

  • مؤلف
  • تاريخ آخر تغيير رئيسي
  • قائمة بمراجعين، بما في ذلك مراجع واحد (فقطمراجع محتمل
  • الوضع الحاليمسودة ،قيد المراجعة ،موافَق عليه ،تم الرفض ، جارٍ التنفيذ ،تم التنفيذ )
  • رابط إلى سلسلة محادثات (ستتم إضافته بعد الإعلان)

يمكن كتابة المستند إما كمستند Google قابل للقراءة عالميًا أو باستخدام Markdown. يمكنك الاطّلاع أدناه على معلومات حول مقارنة بين "مستندات Google" و"مستندات Google".

يجب أن تتضمّن الاقتراحات التي يكون لها تأثير مرئي للمستخدم قسمًا يوثّر التأثير على التوافق مع الأنظمة القديمة (وخطة طرح إذا لزم الأمر).

إنشاء طلب سحب

يمكنك مشاركة مستند التصميم من خلال إنشاء طلب سحب (PR) لإضافة المستند إلى فهرس التصميم. أضِف ملف تسجيل الدخول أو رابط مستند إلى خادم العلاقات العامة.

إذا أمكن، اختَر مُراجعًا محتملاً مع إرسال نسخة إلى المُراجعين الآخرين. إذا لم تختَر مراجعًا محتملاً، سيخصّص الرئيس المسؤول عن البازيل أحد العلاقات العامة.

بعد أن تنشئ العلاقات العامة، يمكن للمراجعين إضافة تعليقات أولية أثناء مراجعة الرمز. على سبيل المثال، يمكن أن يقترح المراجع المحتمل مراجعين إضافيين أو يشير إلى المعلومات الناقصة. ويوافق المراجع المحتمل على العلاقات العامة عندما يؤمن بأنّ عملية المراجعة يمكن أن تبدأ. هذا لا يعني أن الاقتراح مثالي أو أنه ستتم الموافقة عليه؛ فهذا يعني أن الاقتراح يحتوي على معلومات كافية لبدء المناقشة.

الإعلان عن الاقتراح الجديد

أرسِل إشعارًا إلى bazel-dev عندما يتم إرسال العلاقات العامة.

يمكنك نسخ مجموعات أخرى (على سبيل المثال، bazel-مناقشة، للحصول على تعليقات من مستخدمي Bazel).

تكرار التعليقات مع المراجعين

يمكن لأي شخص مهتم التعليق على اقتراحك. حاوِل الإجابة عن الأسئلة وتوضيح الاقتراح ومعالجة المخاوف.

من المفترض أن تتم المناقشة في سلسلة الإعلانات. إذا كان الاقتراح في مستند Google، يمكن استخدام التعليقات بدلاً من ذلك (تجدر الإشارة إلى أنه يتم السماح بالتعليقات المجهولة).

تحديث الحالة

يمكنك إنشاء علاقات عامة جديدة لتعديل حالة الاقتراح عند اكتماله. أرسِل العلاقات العامة إلى مراجع العملاء المحتملين نفسه مع إرسال نسخة إلى المراجعين الآخرين.

لقبول الاقتراح رسميًا، يوافق المراجع المحتمل على العلاقات العامة بعد ضمان موافقة المراجعين الآخرين على القرار.

يجب أن يكون هناك أسبوع واحد على الأقل بين الإعلان الأول والموافقة على الاقتراح. وهذا يضمن للمستخدمين الوقت الكافي لقراءة المستند ومشاركة مخاوفهم.

يمكن أن يبدأ التنفيذ قبل قبول الاقتراح، على سبيل المثال، إثبات مفهوم أو تجربة. ومع ذلك، لا يمكنك إرسال التغيير قبل اكتمال المراجعة.

اختيار مراجع محتمل

يجب أن يكون المراجع المحتمل خبيرًا في النطاق يكون:

  • دراية بالأنظمة الفرعية ذات الصلة
  • الغرض والقدرة على تقديم ملاحظات بنّاءة
  • متاحة خلال فترة المراجعة بالكامل لقيادة العملية

ننصحك بالاطّلاع على جهات الاتصال بحثًا عن تصنيفات الفريق المختلفة.

Markdown مقابل "مستندات Google"

حدد أفضل طريقة تناسبك، بما أن كليهما مقبول.

مزايا استخدام "مستندات Google":

  • فعّال لتبادل الأفكار، لأنه سهل البدء.
  • التعديل التعاوني
  • تكرار سريع.
  • طريقة سهلة لاقتراح تعديلات.

مزايا استخدام ملفات Markdown:

  • محو عناوين URL للربط.
  • سجلّ صريح للنُسخ السابقة
  • لا تنسَ إعداد حقوق الوصول قبل نشر الرابط.
  • يمكن البحث عنها بسهولة باستخدام محرّكات البحث.
  • معالجة مستقبلية: لا يتم اعتبار النص العادي رهن أي أداة خاصة، ولا يتطلب ذلك اتصالاً بالإنترنت.
  • من الممكن تعديلها حتى إذا لم يعُد المؤلف متوفرًا بعد الآن.
  • ويمكن معالجتها تلقائيًا (تحديث/رصد الروابط المعطّلة، أو جلب قائمة بالمؤلفين، وما إلى ذلك).

يمكنك اختيار مراجعة المحتوى في "مستند Google" أولاً، ثم تحويله إلى ترميز للأبدية.

استخدام "مستندات Google"

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

لجعل المستند مقروءًا للجميع، انقر على مشاركة > إعدادات متقدمة > تغيير...، واختر "تشغيل - أي شخص لديه الرابط". إذا سمحت بالتعليقات على المستند، يمكن لأي شخص التعليق بدون الكشف عن هويته، حتى بدون امتلاك حساب Google.

استخدام Markdown

يتم تخزين المستندات على GitHub وتستخدم صيغة GitHub من Markdown (المواصفات).

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

سير عمل المُراجِع

يضيف أحد المراجعين تعليقًا على مستندات التصميم ويوافق عليها.

مسؤوليات المراجع العامة

وتقع على عاتقك مسؤولية مراجعة مستندات التصميم، وطلب المعلومات الإضافية إذا لزم الأمر، والموافقة على التصميم الذي اجتاز عملية المراجعة.

عندما تتلقى اقتراحًا جديدًا

  1. ألقِ نظرة سريعة على المستند.
  2. علِّق في حال عدم توفّر معلومات مهمة، أو إذا كان التصميم لا يلائم أهداف المشروع.
  3. اقتراح مراجعين إضافيين
  4. يمكنك الموافقة على العلاقات العامة عندما تكون جاهزة للمراجعة.

أثناء عملية المراجعة

  1. شارِك في حوار مع مؤلف التصميم حول المشاكل التي تحتاج إلى توضيح.
  2. إذا كان ذلك مناسبًا، يمكنك دعوة تعليقات من غير المراجعين الذين ينبغي أن يكونوا على دراية بالتصميم.
  3. حدِّد التعليقات التي يجب أن يعالجها المؤلف كشرط أساسي للموافقة عليها.
  4. اكتب "LGTM" (Looks Good to Me) في سلسلة محادثات عندما تكون راضيًا عن الوضع الحالي للاقتراح.

يمكنك اتباع هذه العملية لكل طلبات مراجعة التصميم. لا توافق على التصاميم التي تؤثّر في Bazel إذا لم تكن مدرَجة في فهرس التصميم.

مسؤوليات المراجع الرئيسي

أنت مسؤول عن اتّخاذ قرار البدء / الإيقاف عند تنفيذ تصميم في انتظار المراجعة. إذا تعذّر عليك إجراء ذلك، عليك تحديد مفوَّض مناسب (إعادة تحديد مسؤول العلاقات العامة للمفوّض) أو إعادة تخصيص الخطأ إلى مدير البازيل لمزيد من التصرف.

أثناء عملية المراجعة

  1. تأكّد من أن عملية تكرار التعليقات والتصميم تستمر بطريقة بنّاءة.
  2. قبل الحصول على الموافقة، تأكّد من أنّه تم حلّ مخاوف المراجعين الآخرين.

بعد موافقة جميع المراجعين

  1. تأكد من مرور أسبوع واحد على الأقل منذ الإعلان عن الإعلان في القائمة البريدية.
  2. تأكّد من أن الممثّل الرسمي يحدّث الحالة.
  3. الموافقة على العلاقات العامة التي أرسلها مؤلف الاقتراح

رفض التصاميم

  1. تأكّد من أن مؤلف العلاقات العامة يُرسل العلاقات العامة. أو أرسل إليهم العلاقات العامة.
  2. يُحدّث العلاقات العامة حالة المستند.
  3. أضِف تعليقًا إلى المستند لتوضيح سبب عدم الموافقة على التصميم في حالته الحالية، مع توضيح الخطوات التالية، إن وجدت (مثل "مراجعة الافتراضات غير الصالحة وإعادة الإرسال").