افزودن اطلاعات تغییرات برای یادداشت‌های نسخه¶

بسیاری از ابزارهای BeeWare از towncrier برای کمک به ساخت یادداشت‌های انتشار هر نسخه استفاده می‌کنند. وقتی یک درخواست کشش (pull request) را به یکی از ابزارهای مربوطه ارسال می‌کنید، باید شامل یک یادداشت تغییر باشد – این یادداشت تغییر تبدیل به مدخلی در یادداشت‌های انتشار می‌شود که تغییر انجام‌شده را توصیف می‌کند.

هر درخواست کشش باید حداقل یک فایل در دایرکتوری changes/ داشته باشد که توضیح کوتاهی از تغییری که توسط درخواست کشش پیاده‌سازی شده ارائه دهد. یادداشت تغییر باید به فرمت مارک‌داون باشد، در فایلی با نامی به شکل <id>.<fragment type>.md. اگر تغییری که پیشنهاد می‌دهید یک باگ را رفع می‌کند یا ویژگی‌ای را پیاده‌سازی می‌کند که برای آن شماره ایزیس (issue) موجود است، شناسه همان شماره تیکت خواهد بود. اگر تغییر مربوط به هیچ ایرادی نباشد، شماره PR می‌تواند به‌عنوان شناسه استفاده شود. شما تا قبل از ارسال درخواست کشش این شماره را نخواهید دانست، بنابراین اولین مرحله CI در بررسی towncrier شکست خواهد خورد؛ یادداشت تغییر را اضافه کرده و یک به‌روزرسانی PR ارسال کنید تا CI با موفقیت عبور کند.

پنج نوع قطعه وجود دارد:

feature: PR یک رفتار یا قابلیت جدید را اضافه می‌کند که قبلاً امکان‌پذیر نبود (مثلاً افزودن پشتیبانی از یک قالب بسته‌بندی جدید، یا یک ویژگی جدید در یک قالب بسته‌بندی موجود)؛
bugfix: این PR یک باگ در پیاده‌سازی موجود را رفع می‌کند؛
doc: PR یک بهبود قابل توجه در مستندات است؛
removal; PR نمایانگر یک تغییر ناسازگار رو به عقب در رابط برنامه‌نویسی کاربردی BeeWare است؛ یا
misc; یک تغییر جزئی یا اداری (مثلاً اصلاح یک اشتباه تایپی، یک توضیح زبانی جزئی، یا به‌روزرسانی نسخهٔ یک وابستگی) که نیازی به اعلام در یادداشت‌های انتشار ندارد.

این توضیح در یادداشت تغییر باید یک خلاصه سطح بالا و «بازاریابی» از تغییر از دیدگاه کاربر باشد، نه یک توضیح فنی عمیق یا جزئیات پیاده‌سازی. این با پیام commit متفاوت است – پیام commit شرح می‌دهد چه کاری انجام شده تا توسعه‌دهندگان آینده بتوانند دلیل تغییر را دنبال کنند؛ یادداشت تغییر توصیفی است برای بهره‌مندی کاربران که ممکن است از ساختار داخلی اطلاع نداشته باشند.

برای مثال، اگر شما یک باگ مربوط به نام‌گذاری پروژه را رفع کنید، پیام کامیت ممکن است چنین باشد:

یک بررسی عبارت منظم قوی‌تر اعمال کنید تا نام‌های پروژه‌هایی که با اعداد شروع می‌شوند، مجاز نباشند.

یادداشت تغییر مربوطه چیزی شبیه به این خواهد بود:

نام پروژه‌ها دیگر نمی‌توانند با عدد شروع شوند.

برخی PRها ممکن است چندین ویژگی را معرفی کنند و چندین باگ را رفع نمایند، یا چندین تغییر ناسازگار رو به عقب را اعمال کنند. در این صورت، PR ممکن است چندین فایل یادداشت تغییر داشته باشد. اگر نیاز باشد دو نوع قطعه را با یک شناسه یکسان مرتبط کنید، می‌توانید یک پسوند عددی اضافه کنید. برای مثال، اگر PR 789 ویژگی‌ای را که در تیکت 123 توصیف شده بود اضافه کرده، باگی را که در تیکت 234 توصیف شده بود بسته و همچنین دو تغییر ناسازگار رو به عقب ایجاد کرده باشد، ممکن است 4 فایل یادداشت تغییر داشته باشید:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

برای اطلاعات بیشتر درباره towncrier و انواع فرگمنت‌ها به News Fragments مراجعه کنید. همچنین می‌توانید نمونه‌های موجود فرگمنت‌های خبری را در دایرکتوری changes از مخزن BeeWare مشاهده کنید. اگر این پوشه خالی باشد، احتمالاً به این دلیل است که BeeWare به‌تازگی یک نسخهٔ جدید منتشر کرده است؛ فایل‌های یادداشت تغییرات با هر نسخه حذف و ترکیب می‌شوند تا یادداشت‌های نسخه به‌روزرسانی شوند. می‌توانید آن فایل را ببینید تا با سبک کامنت مورد نیاز آشنا شوید؛ همچنین می‌توانید به PRهای اخیراً ادغام‌شده مراجعه کنید تا نحوه قالب‌بندی یادداشت‌های تغییرات خود را مشاهده کنید.