نسخهها و سیاست تغییرات
کاشی از نسخهٔ ۱.۰ قول میدهد که API کامپوننتها بیخبر نشکند؛ هر حذفی دستکم یک نسخه پیشتر «منسوخ» اعلام میشود و هر نسخهٔ اصلی راهنمای مهاجرت دارد.
از نسخهٔ ۱.۰، کاشی برای استفاده در محصولات سازمانی پایدار است. این صفحه میگوید چه چیزی ثابت میماند، چه چیزی چطور عوض میشود و هر نسخه تا کی پشتیبانی میشود.
شمارهٔ نسخه
کاشی از Semantic Versioning پیروی میکند. همهٔ پکیجها (@kashi-ui/react، css، elements، persian، tokens، icons، bank-logos، tailwind و mcp) با یک شمارهٔ نسخه منتشر میشوند تا هیچوقت لازم نباشد بپرسید کدام با کدام سازگار است.
| تغییر | مثال | نسخه |
|---|---|---|
| رفع باگ، بهتر شدن ظاهر بدون تغییر API | فاصلهٔ درست بین برچسب و فیلد | 1.0.0 ← 1.0.1 |
| قابلیت یا کامپوننت تازه، prop اختیاری تازه | کامپوننت انتخاب نوبت | 1.0.1 ← 1.1.0 |
| تغییر ناسازگار | حذف یا تغییر نام prop، تغییر مقدار پیشفرض، حذف کلاس CSS | 1.1.0 ← 2.0.0 |
چه چیزهایی API عمومی است
- همهٔ کامپوننتها، propها و نوعهای TypeScript که از
@kashi-ui/reactو@kashi-ui/elementsexport شدهاند. - نام تگهای وب کامپوننت (
kashi-*)، ویژگیها (attributes) و رویدادهایkashi-change. - کلاسهای CSS با پیشوند
k-و متغیرهای CSS با پیشوند--k-. - تابعهای
@kashi-ui/persianو توکنهای@kashi-ui/tokens. - کلیدهای فرهنگ متنها (
faMessages،enMessages).
ساختار داخلی HTML، کلاسها و متغیرهایی که با _ شروع میشوند (مثل --_p) و متن پیشفرض برچسبها جزو API نیستند. متنها ممکن است در نسخهٔ کوچک بهتر شوند؛ اگر به متن دقیقی نیاز دارید، آن را با prop یا messages خودتان بدهید.
منسوخ کردن، پیش از حذف
هیچ قابلیتی بیخبر حذف نمیشود:
۱. اعلام منسوخ شدن در یک نسخهٔ کوچک (مثلاً 1.4.0): قابلیت هنوز کار میکند، در حالت توسعه یک هشدار [kashi] منسوخ: … در کنسول میآید که جایگزین را میگوید، در صفحهٔ همان کامپوننت برچسب «منسوخ» میخورد و در یادداشت نسخهها نوشته میشود.
۲. دستکم یک نسخهٔ کوچک با هر دو راه، قدیمی و جدید، منتشر میشود تا فرصت مهاجرت داشته باشید.
۳. حذف فقط در نسخهٔ اصلی بعدی (مثلاً 2.0.0)، همراه با راهنمای مهاجرت.
هشدارها فقط در حالت توسعه نشان داده میشوند و در بیلد production هیچ هزینهای ندارند.
راهنمای مهاجرت
هر نسخهٔ اصلی صفحهٔ مهاجرت خودش را دارد: چه چیزی عوض شده، چرا، و کد قبل و بعد برای هر مورد. مهاجرت به ۲.۰ و ۱.۰
مدت پشتیبانی
| نسخه | وضعیت | پشتیبانی |
|---|---|---|
| ۱.x | فعلی | قابلیت تازه، رفع باگ و رفع امنیتی |
| ۰.x | قدیمی | به ۱.۰ مهاجرت کنید؛ مهاجرت تغییر کدی لازم ندارد |
وقتی نسخهٔ ۲.۰ منتشر شود، ۱.x تا ۱۲ ماه رفعهای امنیتی و باگهای جدی را میگیرد. جزئیات گزارش و رفع آسیبپذیریها در امنیت آمده است.
سازگاری
| پشتیبانیشده | |
|---|---|
| React | ۱۸ و ۱۹؛ در App Router نکست کامپوننتها در صفحههای سرور هم کار میکنند |
| فریمورکها | Next.js (در هر تغییر خودکار نصب و بیلد میشود)، Vite، Remix؛ وب کامپوننتها برای Vue، Svelte، Angular و HTML |
| مرورگرها | Chrome و Edge ۱۲۰+، Firefox ۱۲۱+، Safari ۱۶٫۴+ (iOS و macOS) |
| Tailwind | ۳ و ۴ |
| Node.js (برای ابزارها) | ۲۲ به بالا |
چطور کیفیت حفظ میشود
در هر تغییر، پیش از انتشار:
- تست رفتار برای همهٔ کامپوننتها، ابزارهای فارسی و وب کامپوننتها.
- تست دوزبانه: همهٔ کامپوننتها به انگلیسی رندر میشوند و نباید حتی یک حرف فارسی در متنهایشان بماند.
- تست تصویری: از همهٔ نمونههای این سایت و حالتهای حساس (خطا کنار فیلد بیخطا، متن بلند، غیرفعال، انگلیسی) در تم روشن و تیره عکس گرفته و با عکس مرجع مقایسه میشود.
- سقف حجم: هر کامپوننت سقف حجم دارد و بزرگتر شدنش بیاجازه ممکن نیست. حجم کامپوننتها
- کنتراست رنگ همهٔ جفترنگهای تم با WCAG 2.2 AA.
- نصب واقعی در یک پروژهٔ Next.js، با npm و با shadcn.
- کیت فیگما در شبیهساز اجرا و پیکسلبهپیکسل با CSS مقایسه میشود.