إضافة معلومات التغيير لملاحظات الإصدار

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

يجب أن يتضمن كل طلب سحب ملفًا واحدًا على الأقل في دليل changes/ يوفر وصفًا موجزًا للتغيير الذي تم تنفيذه بواسطة طلب السحب. يجب أن تكون ملاحظة التغيير بتنسيق Markdown، في ملف يحمل اسم التنسيق <id>.<fragment type>.md. إذا كان التغيير الذي تقترحه سيصلح خطأً أو ينفذ ميزة لها رقم مشكلة موجود، فسيكون المعرف هو رقم تلك التذكرة. إذا لم يكن للتغيير مشكلة مقابلة، فيمكن استخدام رقم PR كرقم تعريف. لن تعرف رقم PR هذا حتى تقوم بدفع طلب السحب، لذا ستفشل أول عملية CI في فحص towncrier؛ أضف ملاحظة التغيير وقم بدفع تحديث PR وستنجح عملية CI.

هناك خمسة أنواع من الأجزاء:

• الميزة: يضيف PR سلوكًا أو إمكانية جديدة لم تكن ممكنة من قبل (على سبيل المثال، إضافة دعم لتنسيق تغليف جديد، أو ميزة جديدة في تنسيق تغليف موجود بالفعل)؛
• bugfix: يعمل PR على إصلاح خطأ في التنفيذ الحالي؛
• doc: تمثل العلاقات العامة تحسناً كبيراً في التوثيق؛
• إزالة؛ يمثل PR تغييرًا غير متوافق مع الإصدارات السابقة في BeeWare API؛ أو
• misc؛ تغيير بسيط أو إداري (مثل تصحيح خطأ مطبعي أو توضيح لغوي بسيط أو تحديث إصدار تابع) لا يحتاج إلى الإعلان عنه في ملاحظات الإصدار.

يجب أن يكون هذا الوصف في ملاحظة التغيير ملخصًا "تسويقيًا" عالي المستوى للتغيير من منظور المستخدم، وليس وصفًا تقنيًا عميقًا أو تفاصيل التنفيذ. وهو يختلف عن رسالة الالتزام - حيث تصف رسالة الالتزام ما تم القيام به حتى يتمكن المطورون في المستقبل من متابعة أسباب التغيير؛ أما ملاحظة التغيير فهي وصف لصالح المستخدمين، الذين قد لا يكون لديهم معرفة بالجوانب الداخلية.

على سبيل المثال، إذا قمت بإصلاح خطأ متعلق بتسمية المشروع، فقد يكون نص رسالة الالتزام كما يلي:

تطبيق فحص تعبير عادي أقوى لمنع أسماء المشاريع التي تبدأ بأرقام.

ستكون ملاحظة التغيير المقابلة كما يلي:

لم يعد من الممكن أن تبدأ أسماء المشاريع بأرقام.

بعض طلبات السحب (PR) ستقدم ميزات متعددة وتصلح أخطاء متعددة، أو تقدم تغييرات متعددة غير متوافقة مع الإصدارات السابقة. في هذه الحالة، قد يحتوي PR على عدة ملفات ملاحظات تغيير. إذا كنت بحاجة إلى ربط نوعين من الأجزاء بنفس المعرف، يمكنك إضافة لاحقة رقمية. على سبيل المثال، إذا أضاف PR 789 ميزة موصوفة في التذكرة 123، وأغلق خطأ موصوف في التذكرة 234، وأجرى أيضًا تغييرين غير متوافقين مع الإصدارات السابقة، فقد يكون لديك 4 ملفات ملاحظات تغيير:

• 123.feature.md
• 234.تصحيح الأخطاء.md
• 789.removal.1.md
• 789.removal.2.md

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