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

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

## ساختار فایل

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

```json
{
  "date": "1405/07/05",
  "description": "توضیح کاربرپسند و فارسیِ تغییر، به شکل یک جملهٔ کوتاه."
}
```

- `date`: تاریخ شمسی به قالب `yyyy/mm/dd`.
- `description`: توضیح فارسیِ روان (نه ترجمهٔ تحت‌اللفظیِ پیام Commit)، مناسب
  برای خواننده‌ای که کاربر نهایی سایت است، نه توسعه‌دهنده.
- آرایه باید به ترتیب **صعودی** (قدیم به جدید) در فایل نگه داشته شود؛ نمایش
  معکوس (جدید به قدیم) در سمت کلاینت با جاوااسکریپت (`_FooterPartial.cshtml`)
  انجام می‌شود.

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

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

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

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

   ```bash
   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. فایل به‌روزشده را جایگزین `DivanRazor/wwwroot/json/changelog.json` کنید و
   کامیت نمایید.

## نمایش در سایت

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