anas/divan
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity
8a981bf993
divan/docs/CHANGELOG_PROCESS.md
Hamid Reza Mohammadi 1351679a21 ganjoor software changelog
2026-09-27 18:06:03 +03:30

3.9 KiB
Raw Blame History

فرایند نگهداری فهرست تغییرات (Changelog)

فایل GanjooRazor/wwwroot/json/changelog.json فهرست تغییرات کاربرپسند این پروژه را به زبان فارسی نگه می‌دارد و در پاورقی سایت («تازه‌های نرم‌افزار») نمایش داده می‌شود.

ساختار فایل

فایل یک آرایهٔ JSON است که هر عضو آن به این شکل است:

{
  "date": "1405/07/05",
  "description": "توضیح کاربرپسند و فارسیِ تغییر، به شکل یک جملهٔ کوتاه."
}
  • date: تاریخ شمسی به قالب yyyy/mm/dd.
  • description: توضیح فارسیِ روان (نه ترجمهٔ تحت‌اللفظیِ پیام Commit)، مناسب برای خواننده‌ای که کاربر نهایی سایت است، نه توسعه‌دهنده.
  • آرایه باید به ترتیب صعودی (قدیم به جدید) در فایل نگه داشته شود؛ نمایش معکوس (جدید به قدیم) در سمت کلاینت با جاوااسکریپت (_FooterPartial.cshtml) انجام می‌شود.

فقط تغییراتی که یک کاربر عادی سایت متوجهٔ آن می‌شود باید وارد این فایل شوند: ویژگی‌های جدید، تغییرات محسوس رابط کاربری، رفع اشکال‌های قابل‌مشاهده، بهبودهای کارایی محسوس و غیره. تغییرات صرفاً فنی (ریفکتور، بروزرسانی وابستگی‌ها، CI/CD، migrationهای دیتابیس، تمیزکاری کد، تایپو در کد) نباید در این فایل بیایند.

به‌روزرسانی فهرست تغییرات پس از هر دوره از توسعه

از آنجا که نوشتن توضیح فارسیِ طبیعی و تشخیص اینکه کدام Commitها واقعاً برای کاربر اهمیت دارند به قضاوت نیاز دارد (نه صرفاً یک تبدیل خودکار متن)، روش پیشنهادی برای به‌روزرسانی، استفاده از دستیار هوش مصنوعی (مثلاً Claude) است:

  1. لیست Commitهای جدید را از زمان آخرین به‌روزرسانی فهرست تغییرات بگیرید:

    git log --no-merges --date=format:'%Y-%m-%d' --pretty=format:'%H|%ad|%s' \
    --since="<تاریخ آخرین به‌روزرسانی>" > new_commits.txt

  2. این فایل را همراه با فایل فعلی changelog.json به دستیار بدهید و از آن بخواهید:

    • Commitهای بی‌اهمیت برای کاربر نهایی را کنار بگذارد.
    • Commitهای مرتبط با یک ویژگی/رفع‌اشکال را در یک مورد ادغام کند.
    • برای هر مورد باقی‌مانده یک توضیح فارسیِ طبیعی و کوتاه بنویسد.
    • تاریخ میلادی هر Commit را به شمسی (yyyy/mm/dd) تبدیل کند.
    • موارد جدید را در انتهای آرایهٔ موجود در changelog.json اضافه کند (نه جایگزینی کل فایل)، با حفظ ترتیب صعودی تاریخ.

  3. فایل به‌روزشده را جایگزین GanjooRazor/wwwroot/json/changelog.json کنید و کامیت نمایید.

نمایش در سایت

پاورقی سایت (GanjooRazor/Pages/Shared/_FooterPartial.cshtml) یک لینک با عنوان «تازه‌های نرم‌افزار» دارد که با کلیک، پنجرهٔ Modal مربوطه را باز کرده و فایل changelog.json را با fetch بارگذاری می‌کند. لیست به‌صورت معکوس (جدیدترین مورد در بالا) نمایش داده می‌شود. سبک‌های مربوط به این بخش در GanjooRazor/wwwroot/css/p8.css (کلاس‌های .changelog-*) تعریف شده‌اند.