كتابة ملاحظات الإصدار

يستهدف هذا المستند المساهمين في Bazel.

تتضمّن أوصاف الالتزام في Bazel علامة RELNOTES: متبوعة بإشعار إصدار. ويستخدمه فريق Bazel لتتبُّع التغييرات في كل إصدار وكتابة إعلان الإصدار.

نظرة عامة

  • هل تم إجراء تغيير في الخطأ؟ في هذه الحالة، لن تحتاج إلى ملاحظة إصدار. يُرجى تضمين مرجع لمشكلة GitHub.

  • إذا كان التغيير يضيف / يزيل / يغيّر Bazel بطريقة مرئية للمستخدم، قد يكون من المفيد الإشارة إليه.

إذا كان التغيير كبيرًا، اتبع سياسة مستند التصميم أولاً.

الإرشادات

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

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

  • استخدم علامات الاقتباس حول الرمز أو الرموز أو العلامات أو أي كلمة تحتوي على شرطة سفلية.

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

  • استخدِم التوتر الحالي دائمًا والتنسيق "Bazel الآن متوافق مع Y" أو "X الآن Z". لا نريد ظهور ملاحظات الإصدار كإدخالات للأخطاء. يجب أن تكون جميع الإدخالات في ملاحظات الإصدار مفيدة وأن تستخدم أسلوبًا ولغة متسقة.

  • إذا تم إيقاف عنصر أو إزالته، استخدِم عبارة "تم إيقاف X" أو "تمت إزالة X". ليست "تمت الإزالة" أو "تمت إزالتها".

  • إذا تغيّر اسم بازل الآن بطريقة مختلفة، استخدِم "X الآن $newالسلوك بدلاً من $oldالسلوك" في الوقت الحالي. يتيح ذلك للمستخدم معرفة ما يمكن توقعه عند استخدام الإصدار الجديد بالتفصيل.

  • إذا كان Bazel الآن متوافقًا أو لم يعد متوافقًا، استخدِم "Bazel الآن متوافقًا مع X أو لم يعد متوافقًا".

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

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

معالجة

وفي إطار عملية الإصدار، نجمع علامات RELNOTES لكل عملية تنفيذ. وننسخ كل المحتوى في مستند Google الذي يمكننا من خلاله مراجعة الملاحظات وتعديلها وتنظيمها.

ويرسل مدير الإصدار رسالة إلكترونية إلى القائمة البريدية bazel-dev. تتم دعوة المساهمين في Bazel للمساهمة في المستند والتأكّد من أن التغييرات التي نجريها تنعكس بشكل صحيح في الإعلان.

بعد ذلك، سيتم إرسال الإشعار إلى مدونة Bazel، باستخدام مستودع Bazel.