arc/docs/VERSION_MANAGEMENT.md

مدیریت نسخه سراسری

این پروژه از یک سیستم مدیریت نسخه سراسری استفاده می‌کند که نسخه را در یک مکان مرکزی (pubspec.yaml) نگهداری می‌کند و Flutter به طور خودکار آن را به تمام پلتفرم‌ها منتقل می‌کند.

نحوه کار

نسخه در فایل hesabixUI/hesabix_ui/pubspec.yaml به صورت زیر تعریف می‌شود:

version: 1.0.23+23

فرمت: MAJOR.MINOR.PATCH+BUILD

• MAJOR: نسخه اصلی (تغییرات بزرگ و ناسازگار)
• MINOR: نسخه فرعی (ویژگی‌های جدید، سازگار با قبل)
• PATCH: نسخه اصلاحی (رفع باگ‌ها)
• BUILD: شماره بیلد (برای هر بیلد افزایش می‌یابد)

Flutter به طور خودکار این نسخه را به پلتفرم‌های زیر منتقل می‌کند:

• Android: versionName (MAJOR.MINOR.PATCH) و versionCode (BUILD)
• iOS: CFBundleShortVersionString (MAJOR.MINOR.PATCH) و CFBundleVersion (BUILD)
• Windows: FLUTTER_VERSION_MAJOR, MINOR, PATCH, BUILD
• Linux: از pubspec.yaml خوانده می‌شود
• macOS: CFBundleShortVersionString و CFBundleVersion
• Web: از pubspec.yaml خوانده می‌شود

هم‌ترازی با ریلیز اندروید (Forgejo)

از این پس برای APKهای منتشرشده در ریلیزهای مخزن:

• versionName / تگ ریلیز باید یکسان باشد: MAJOR.MINOR.PATCH (مثلاً 70.9.911)
• versionCode پیشنهادی: MAJOR * 1000000 + MINOR * 1000 + PATCH
• جزئیات به‌روزرسانی خودکار: docs/ANDROID_AUTO_UPDATE.md
• به‌روزرسانی خودکار ویندوز (همان تگ ریلیز، asset جدا): docs/WINDOWS_AUTO_UPDATE.md

مثال در pubspec.yaml:

version: 70.9.911+70009911

استفاده از اسکریپت‌های مدیریت نسخه

Linux/macOS (Bash)

# نمایش نسخه فعلی
./update_version.sh --show

# تنظیم نسخه به 1.0.24 (شماره بیلد تغییر نمی‌کند)
./update_version.sh --set 1.0.24

# تنظیم شماره بیلد به 24
./update_version.sh --build 24

# تنظیم نسخه کامل
./update_version.sh --set-full 1.0.24+24

# افزایش نسخه patch (1.0.23 -> 1.0.24)
./update_version.sh --increment patch

# افزایش نسخه minor (1.0.23 -> 1.1.0)
./update_version.sh --increment minor

# افزایش نسخه major (1.0.23 -> 2.0.0)
./update_version.sh --increment major

# افزایش شماره بیلد (23 -> 24)
./update_version.sh --increment build

Windows (PowerShell)

# نمایش نسخه فعلی
.\update_version.ps1 -Show

# تنظیم نسخه به 1.0.24
.\update_version.ps1 -Set 1.0.24

# تنظیم شماره بیلد به 24
.\update_version.ps1 -Build 24

# تنظیم نسخه کامل
.\update_version.ps1 -SetFull 1.0.24+24

# افزایش نسخه patch
.\update_version.ps1 -Increment patch

# افزایش نسخه minor
.\update_version.ps1 -Increment minor

# افزایش نسخه major
.\update_version.ps1 -Increment major

# افزایش شماره بیلد
.\update_version.ps1 -Increment build

مثال‌های عملی

سناریو 1: انتشار نسخه جدید با رفع باگ

# افزایش patch و build
./update_version.sh --increment patch
./update_version.sh --increment build

یا به صورت یکجا:

# افزایش patch (build هم باید افزایش یابد)
./update_version.sh --increment patch
./update_version.sh --increment build

سناریو 2: افزودن ویژگی جدید

# افزایش minor (patch و build به 0 برمی‌گردند)
./update_version.sh --increment minor
./update_version.sh --increment build

سناریو 3: تغییرات بزرگ

# افزایش major (minor, patch و build به 0 برمی‌گردند)
./update_version.sh --increment major
./update_version.sh --increment build

سناریو 4: تنظیم دستی نسخه

# تنظیم نسخه کامل
./update_version.sh --set-full 2.0.0+50

نکات مهم

1. همیشه قبل از بیلد، نسخه را بررسی کنید: از --show استفاده کنید
2. شماره بیلد باید همیشه افزایش یابد: برای هر بیلد جدید، build number را افزایش دهید
3. نسخه‌گذاری معنادار: از semantic versioning پیروی کنید
4. پس از تغییر نسخه، بیلد کنید: تغییرات در pubspec.yaml فقط در بیلدهای بعدی اعمال می‌شوند

بررسی نسخه در خروجی‌های بیلد

Android

# بررسی APK
aapt dump badging app-release.apk | grep version

iOS

نسخه در Info.plist و project.pbxproj تنظیم می‌شود.

Windows

نسخه در Runner.rc و خواص فایل EXE قابل مشاهده است.

عیب‌یابی

اگر نسخه در پلتفرم خاصی اعمال نشد:

1. مطمئن شوید که pubspec.yaml به درستی به‌روزرسانی شده است
2. پروژه را clean کنید: flutter clean
3. دوباره بیلد کنید: flutter build <platform>
4. بررسی کنید که فایل‌های native (مثل build.gradle.kts برای Android) از متغیرهای Flutter استفاده می‌کنند