63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# فرایند نگهداری فهرست تغییرات (Changelog)
|
||
|
||
فایل `GanjooRazor/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. فایل به‌روزشده را جایگزین `GanjooRazor/wwwroot/json/changelog.json` کنید و
|
||
کامیت نمایید.
|
||
|
||
## نمایش در سایت
|
||
|
||
پاورقی سایت (`GanjooRazor/Pages/Shared/_FooterPartial.cshtml`) یک لینک با
|
||
عنوان «تازه‌های نرم‌افزار» دارد که با کلیک، پنجرهٔ Modal مربوطه را باز کرده و
|
||
فایل `changelog.json` را با `fetch` بارگذاری می‌کند. لیست به‌صورت معکوس
|
||
(جدیدترین مورد در بالا) نمایش داده می‌شود. سبک‌های مربوط به این بخش در
|
||
`GanjooRazor/wwwroot/css/p8.css` (کلاس‌های `.changelog-*`) تعریف شده‌اند.
|