Yugen UI

Phiên bản & chính sách thay đổi

Yugen UI theo Semantic Versioning. Thay đổi phá vỡ luôn được báo trước bằng cảnh báo deprecate, ghi trong CHANGELOG và trang Có gì mới — để bạn nâng cấp có kế hoạch, không bất ngờ.

Semantic Versioning

MAJOR.MINOR.PATCH — đọc số phiên bản là biết mức rủi ro khi nâng cấp.

Phần tăngÝ nghĩaVí dụ
PATCH 1.2.3 → 1.2.4Sửa lỗi, cải thiện a11y / hiệu năng; không đổi API.Sửa focus ring bị cắt trong Dialog
MINOR 1.2.3 → 1.3.0Thêm component, prop, token, biến thể; đánh dấu deprecate.Thêm prop presets cho DateRangePicker
MAJOR 1.2.3 → 2.0.0Xoá API đã deprecate hoặc thay đổi phá vỡ khác.Bỏ appearance="transparent"

Quy tắc cho từng số

Phần lớn thay đổi ra ở bản patch. Minor và major chỉ tăng khi có lý do.

SốTăng khiKhông tăng choNhịp phát hành
PATCH x.y.ZSửa lỗi (kể cả lỗi do bản trước gây ra), a11y, hiệu năng, kiểu TypeScript sai, tinh chỉnh giao diện nhỏ.API mới, thay đổi phá vỡ.Không giới hạn. Các sửa lỗi gần nhau ra chung một bản.
MINOR x.Y.0Có ít nhất một API mới: component, prop, giá trị prop, token, export, template. Đánh dấu deprecate. Trước 1.0: cả thay đổi phá vỡ.Chỉ sửa lỗi hoặc tinh chỉnh.Mỗi milestone một bản, cách bản minor trước ít nhất 14 ngày.
MAJOR X.0.0Thay đổi phá vỡ, từ 1.0. Mọi API đã deprecate được xoá cùng lúc, kèm hướng dẫn chuyển đổi.Tính năng không phá vỡ.Cách bản major trước ít nhất 180 ngày. Trước 1.0 số này là 0.
  • Không nhảy số: sau 0.12.0 là 0.12.1 hoặc 0.13.0.
  • Chỉ đổi trang docs, test hoặc CI thì không ra bản mới. Docs được deploy riêng.
  • main và release/X.Y chỉ ra bản patch. Tính năng vào next và phát hành theo milestone.
  • Bản thử nghiệm (-next.N, canary) không tính.
  • @yugen-ui/cli theo cùng quy tắc với số riêng. create-yugen-ui lên minor cùng @yugen-ui/cli.

Áp dụng cho các bản phát hành sau 0.12.0.

Thế nào là thay đổi phá vỡ

Mọi thứ khiến mã đang chạy đúng phải sửa mới chạy tiếp, hoặc đổi giao diện ngoài ý muốn.

Phá vỡ (chỉ ở major)Không phá vỡ (minor / patch)
Xoá / đổi tên component, prop, giá trị prop, export, hookThêm component, prop tuỳ chọn, giá trị mới cho union
Đổi tên hoặc xoá token / utility (text-foreground-2, p-M…)Thêm token, utility, brand, gradient
Đổi giá trị mặc định làm thay đổi hành vi (vd. modal mặc định)Tinh chỉnh màu / bóng nhỏ trong ngưỡng tương phản đã cam kết
Đổi cấu trúc DOM mà người dùng nhắm tới qua slot / data-*Đổi DOM nội bộ không được ghi trong docs
Nâng yêu cầu tối thiểu (React, Tailwind, trình duyệt)Hỗ trợ thêm phiên bản mới (React 19…)

Quy trình deprecate

Không có API nào biến mất mà không báo trước ít nhất một bản minor.

  1. Bản minor thêm thay thế và đánh dấu API cũ bằng JSDoc @deprecated (gạch ngang trong editor) cùng cảnh báo warnDeprecated() — chỉ ở môi trường phát triển, mỗi API một lần, bị loại khỏi bản build production.
  2. CHANGELOG và trang Có gì mới ghi mục “Thay đổi lớn” với cách chuyển đổi cụ thể.
  3. API cũ vẫn chạy đúng cho tới bản major tiếp theo (tối thiểu một bản minor sau khi deprecate).
  4. Bản major xoá API và giữ hướng dẫn chuyển đổi trong docs.
import { warnDeprecated } from "@/lib/deprecate";

/** @deprecated Dùng `appearance="subtle"`. Sẽ xoá ở v2.0.0. */
if (appearance === "transparent") {
  warnDeprecated("Button.appearance.transparent", 'use appearance="subtle"', "2.0.0");
}

Cảnh báo trong console trông như sau:

[yugen-ui] "Button.appearance.transparent" is deprecated and will be removed in v2.0.0:
use appearance="subtle". See https://trandat1114.github.io/Yugen-UI/concepts/versioning

Yugen Labs

Component thử nghiệm, nằm ngoài SemVer.

Component trong nhóm Yugen Labs còn đang hoàn thiện, và trang của chúng có ghi rõ. API có thể đổi ở một bản minor; CHANGELOG và trang Có gì mới ghi lại thay đổi. Component rời Labs khi đã có test, được một template dùng và API không cần đổi thêm. Từ đó nó theo các quy tắc ở trên.

Phạm vi hỗ trợ

Hạng mụcHỗ trợGhi chú
React18 và 19CI chạy typecheck, unit test và build trên cả hai
Tailwind CSSv4Không cần Tailwind nếu dùng styles.css biên dịch sẵn
TypeScript5.x, strictKiểu được kiểm tra với @types/react 19
Next.jsApp Router & Pages RouterMọi file component có "use client"
Trình duyệtEvergreen (Chrome, Edge, Firefox, Safari 2 bản gần nhất)Xem trang Trình duyệt & nền tảng

Nâng cấp an toàn

  1. Đọc trang Có gì mới từ phiên bản hiện tại tới bản mới, chú ý mục “Thay đổi lớn”.
  2. Chạy ứng dụng ở chế độ phát triển và xử lý mọi cảnh báo [yugen-ui] trong console trước khi lên major.
  3. Chép mã bằng @yugen-ui/cli hoặc shadcn CLI? Commit trước, chạy lại add --overwrite rồi xem diff của git. npx @yugen-ui/cli doctor báo bản yugen-ui đã cũ.
# Giữ trong một dòng minor khi cần ổn định tuyệt đối (giai đoạn 0.x)
npm install yugen-ui@~0.6.0

# Từ 1.0: nhận mọi bản minor / patch, không bao giờ tự lên major
npm install yugen-ui@^1.0.0
Trang trướcTrình duyệt & nền tảngTrang sauBảo mật