مهاجرت و به‌روزرسانی

این بخش برای وقتی است که نسخه جدیدی از قالب می‌گیرید و می‌خواهید بدون از دست دادن تغییرات خودتان ارتقا دهید.

قبل از شروع

از پروژه خود یک شاخه بسازید: git checkout -b upgrade/novaadmin-1.1
فهرست تغییرات خودتان را بنویسید (کدام فایل‌ها را دست زده‌اید؟).
npm run qa:all را روی وضعیت فعلی اجرا کنید تا مطمئن شوید نقطه شروع سالم است.

فایل‌هایی که در نسخه جدید بازنویسی می‌شوند

مسیر	وضعیت	توصیه
`src/pages/**`	تولیدشده	هرگز ویرایش نکنید
`src/locales/generated.js`	تولیدشده	هرگز ویرایش نکنید
`src/data/navigation.js`	تولیدشده	هرگز ویرایش نکنید
`src/partials/docs/*.html`	تولیدشده از `docs/`	به‌جای آن `docs/*.md` (و `docs/en`، `docs/ar`) را ویرایش کنید
`public/robots.txt`, `public/sitemap.xml`	تولیدشده	در `src/config/config.js` تنظیم کنید
`tools/**`	ابزار	تغییرات خود را با diff مقایسه کنید
`src/scss/`, `src/js/`	منبع	تغییرات خود را نگه دارید و با نسخه جدید ادغام کنید

روش ارتقا (گام‌به‌گام)

# ۱. نسخه جدید را در پوشه‌ای جدا باز کنید
unzip NOVAADMIN-1.1.0.zip -d /tmp/nova-1.1

# ۲. ابزارها، استایل و اسکریپت‌ها را به‌روز کنید
rsync -av --exclude=node_modules /tmp/nova-1.1/tools/ ./tools/
rsync -av /tmp/nova-1.1/src/scss/ ./src/scss/
rsync -av /tmp/nova-1.1/src/js/core/ ./src/js/core/

# ۳. وابستگی‌ها را تازه کنید
npm install

# ۴. صفحه‌ها و دارایی‌ها را از نو بسازید
npm run gen:all && npm run build

# ۵. کنترل کیفیت
npm run qa:all

مقایسه تغییرات خودتان

اگر پروژه را با گیت نگه می‌دارید، ساده‌ترین راه این است که تغییرات خود را در چند مسیر محدود نگه دارید:

src/partials/pages/**      بدنه‌های اختصاصی
src/js/pages/**            کنترل‌کننده‌های اختصاصی
src/data/**                داده‌های واقعی شما
src/config/config.js       برند و پیش‌فرض‌ها
src/scss/base/_palettes.scss   پالت سازمانی

هر تغییری بیرون از این فهرست را در فایل UPGRADE-NOTES.md پروژه خودتان ثبت کنید تا در ارتقا یادتان بماند.

تغییرات شکننده را چطور بفهمم؟

نشانه	معنی	کار
خطای import در کنسول	نام یا مسیر فایل تغییر کرده	با `git log` تفاوت را ببینید و مسیر را اصلاح کنید
کلاس بی‌استایل	کلاس حذف یا تغییرنام یافته	`npm run qa:links` لیست را می‌دهد
توکن `{{...}}` در خروجی	توکن جدید اضافه شده	نقشه توکن‌های `tools/nova-plugin.mjs` را به‌روز کنید
انیمیشن یا رفتار دوگانه	دو نسخه از یک ماژول بار شده	import تکراری را حذف کنید

بازگشت به عقب

git checkout -- .
# یا
git reset --hard upgrade/novaadmin-1.0      # اگر شاخه را قبل از ارتقا ساخته باشید

نکته: قبل از هر ارتقا یک بار npm run build بگیرید و خروجی dist/ را نگه دارید؛ اگر مشکلی پیش آمد، همان خروجی را می‌توانید روی هاست بگذارید تا فرصت بررسی داشته باشید

هشدار: فایل‌های تولیدشده را در گیت commit نکنید (به‌جز زمانی که بسته نهایی می‌سازید)، وگرنه در هر ارتقا با تعارض‌های پرحجم روبه‌رو می‌شوید

Migration and upgrades

This section is for when you receive a new version of the template and want to upgrade without losing your own changes.

Before you start

Create a branch in your project: git checkout -b upgrade/novaadmin-1.1
Write down your own changes (which files have you touched?).
Run npm run qa:all on the current state to make sure the starting point is healthy.

Files that are rewritten in a new version

Path	Status	Recommendation
`src/pages/**`	Generated	Never edit
`src/locales/generated.js`	Generated	Never edit
`src/data/navigation.js`	Generated	Never edit
`src/partials/docs/*.html`	Generated from `docs/`	Edit `docs/*.md` (and `docs/en`, `docs/ar`) instead
`public/robots.txt`, `public/sitemap.xml`	Generated	Configure in `src/config/config.js`
`tools/**`	Tooling	Compare your changes with a diff
`src/scss/`, `src/js/`	Source	Keep your changes and merge them with the new version

Upgrade procedure (step by step)

# 1. extract the new version into a separate folder
unzip NOVAADMIN-1.1.0.zip -d /tmp/nova-1.1

# 2. update tools, styles and scripts
rsync -av --exclude=node_modules /tmp/nova-1.1/tools/ ./tools/
rsync -av /tmp/nova-1.1/src/scss/ ./src/scss/
rsync -av /tmp/nova-1.1/src/js/core/ ./src/js/core/

# 3. refresh dependencies
npm install

# 4. rebuild pages and assets
npm run gen:all && npm run build

# 5. quality control
npm run qa:all

Comparing your own changes

If you keep the project in git, the simplest approach is to keep your changes in a few limited paths:

src/partials/pages/**      custom page bodies
src/js/pages/**            custom controllers
src/data/**                your real data
src/config/config.js       brand and defaults
src/scss/base/_palettes.scss   brand palette

Record any change outside this list in your project's own UPGRADE-NOTES.md so you remember it when upgrading.

How do I spot breaking changes?

Symptom	Meaning	Action
Import error in the console	A file name or path changed	Check the difference with `git log` and fix the path
Unstyled class	A class was removed or renamed	`npm run qa:links` gives you the list
A `{{...}}` token in the output	A new token was added	Update the token map in `tools/nova-plugin.mjs`
Doubled animation or behaviour	Two copies of one module were loaded	Remove the duplicate import

Rolling back

git checkout -- .
# or
git reset --hard upgrade/novaadmin-1.0      # if you created the branch before upgrading

Tip: before every upgrade, run npm run build once and keep the dist/ output; if something goes wrong, you can put that output on the host while you investigate

Warning: do not commit generated files to git (except when building the final package), otherwise you will face large conflicts on every upgrade

الترحيل والتحديث

هذا القسم لحين تحصل على إصدار جديد من القالب وتريد الترقية دون فقدان تغييراتك.

قبل البدء

أنشئ فرعاً في مشروعك: git checkout -b upgrade/novaadmin-1.1
دوّن قائمة تغييراتك (ما الملفات التي عدّلتها؟).
نفّذ npm run qa:all على الحالة الحالية للتأكد من سلامة نقطة البداية.

الملفات التي تُعاد كتابتها في الإصدار الجديد

المسار	الحالة	التوصية
`src/pages/**`	مولّد	لا تعدّله أبداً
`src/locales/generated.js`	مولّد	لا تعدّله أبداً
`src/data/navigation.js`	مولّد	لا تعدّله أبداً
`src/partials/docs/*.html`	مولّد من `docs/`	عدّل بدلاً منه `docs/*.md` (و`docs/en` و`docs/ar`)
`public/robots.txt`, `public/sitemap.xml`	مولّد	اضبطه في `src/config/config.js`
`tools/**`	أدوات	قارن تغييراتك بأداة diff
`src/scss/`, `src/js/`	مصدر	احتفظ بتغييراتك وادمجها مع الإصدار الجديد

طريقة الترقية (خطوة بخطوة)

# ١. افتح الإصدار الجديد في مجلد منفصل
unzip NOVAADMIN-1.1.0.zip -d /tmp/nova-1.1

# ٢. حدّث الأدوات والأنماط والسكربتات
rsync -av --exclude=node_modules /tmp/nova-1.1/tools/ ./tools/
rsync -av /tmp/nova-1.1/src/scss/ ./src/scss/
rsync -av /tmp/nova-1.1/src/js/core/ ./src/js/core/

# ٣. جدّد الاعتماديات
npm install

# ٤. أعد بناء الصفحات والأصول
npm run gen:all && npm run build

# ٥. ضبط الجودة
npm run qa:all

مقارنة تغييراتك

إذا كنت تدير المشروع بـ git، فأبسط طريقة هي إبقاء تغييراتك في مسارات محدودة:

src/partials/pages/**      محتويات الصفحات المخصصة
src/js/pages/**            المتحكمات المخصصة
src/data/**                بياناتك الحقيقية
src/config/config.js       العلامة والقيم الافتراضية
src/scss/base/_palettes.scss   لوحة ألوان المؤسسة

سجّل كل تغيير خارج هذه القائمة في ملف UPGRADE-NOTES.md الخاص بمشروعك لتتذكره عند الترقية.

كيف أكتشف التغييرات الكاسرة؟

العَرَض	المعنى	الإجراء
خطأ استيراد في وحدة التحكم	تغيّر اسم ملف أو مساره	اطّلع على الفرق بـ `git log` وصحّح المسار
فئة بلا أنماط	حُذفت الفئة أو أُعيدت تسميتها	يعطيك `npm run qa:links` القائمة
رمز `{{...}}` في المخرجات	أُضيف رمز جديد	حدّث خريطة الرموز في `tools/nova-plugin.mjs`
حركة أو سلوك مزدوج	حُمّلت نسختان من وحدة واحدة	احذف الاستيراد المكرر

التراجع

git checkout -- .
# أو
git reset --hard upgrade/novaadmin-1.0      # إذا أنشأت الفرع قبل الترقية

ملاحظة: قبل كل ترقية نفّذ npm run build مرة واحدة واحتفظ بمخرجات dist/؛ فإن حدثت مشكلة يمكنك وضع تلك المخرجات على الاستضافة ريثما تفحص الأمر

تحذير: لا تُودِع (commit) الملفات المولّدة في git (إلا عند بناء الحزمة النهائية)، وإلا فستواجه تعارضات ضخمة في كل ترقية