Đánh phiên bản và xử lý breaking change
Quy ước đánh số chỉ là phần nhỏ, quan trọng hơn là quy trình thông báo, migration guide và thời gian deprecation đủ để các đội kịp thích nghi.
Chuẩn phổ biến nhất cho design system là semantic versioning (semver), đánh số dạng MAJOR.MINOR.PATCH, trong đó MAJOR tăng khi có breaking change (thay đổi phá vỡ tương thích ngược), MINOR khi thêm tính năng không phá vỡ, PATCH khi sửa lỗi nhỏ. Quan trọng hơn con số là quy trình đi kèm: migration guide rõ ràng, deprecation cycle đủ dài và changelog dễ đọc cho cả đội kỹ thuật lẫn đội thiết kế. Hệ thống không có migration guide thực tế là hệ thống các đội không dám nâng cấp.
Phần lớn đội xây design system dành nhiều công sức cho kiến trúc component nhưng bỏ qua câu hỏi quan trọng không kém: khi hệ thống thay đổi, các đội sản phẩm đang dùng nó sẽ biết gì, biết khi nào, và làm gì tiếp theo? Đánh phiên bản và xử lý breaking change chính là cơ chế trả lời ba câu đó.
Semantic versioning là cam kết, không phải quy ước
Semantic Versioning 2.0.0 (semver) định nghĩa số phiên bản theo cấu trúc MAJOR.MINOR.PATCH. Mỗi con số mang một nghĩa cụ thể và ràng buộc với người dùng thư viện:
- PATCH tăng khi sửa lỗi, không thay đổi giao diện công khai.
- MINOR tăng khi thêm tính năng mới nhưng tương thích ngược hoàn toàn.
- MAJOR tăng khi có breaking change, tức là người dùng buộc phải chỉnh code mới nâng cấp được.
Tăng MAJOR không phải quyết định tùy ý mà là thông báo chính thức: "Anh/Chị cần đọc migration guide trước khi cập nhật." Vì vậy, tăng MAJOR quá thường xuyên sẽ khiến các đội mất tin vào tính ổn định của hệ thống và trì hoãn nâng cấp, tích lũy nợ kỹ thuật dần.
Breaking change thường đến từ đâu
Danh sách kiểm tra dưới đây giúp Anh/Chị phân loại đúng trước khi quyết định tăng phiên bản:
- Đổi tên prop (thuộc tính component) hoặc token (biến thiết kế như màu, khoảng cách, typography).
- Bỏ hẳn một component hoặc variant đang được dùng.
- Thay đổi hành vi mặc định không tương thích, ví dụ button trước đây submit form mặc định, nay không còn.
- Thay đổi cấu trúc DOM hoặc tên CSS class mà đội sản phẩm đang override từ bên ngoài.
Nếu người dùng nâng cấp mà không cần chỉnh bất kỳ file nào, đó không phải breaking change dù thay đổi bên trong có lớn đến đâu.
Deprecation cycle: giai đoạn cảnh báo không thể bỏ qua
Xóa thẳng một component hoặc prop mà không báo trước là lý do phổ biến nhất khiến build của đội sản phẩm vỡ đột ngột và mất tin tưởng vào design system. Thực hành cần thiết là deprecation cycle (chu kỳ cảnh báo): đánh dấu deprecated ít nhất một phiên bản MINOR trước khi xóa, thông báo rõ trong changelog và trong Storybook qua thẻ deprecated, và cho người dùng thời gian thực tế để xử lý, không chỉ thời gian lý thuyết.
Dùng semver đầy đủ MAJOR.MINOR.PATCH khi thư viện được publish lên npm hoặc package registry và nhiều đội dùng độc lập nhau. Dùng versioning theo ngày hoặc số sprint khi chỉ một team dùng trong monorepo và mọi thay đổi được đồng bộ trực tiếp không qua publish. Quy tắc chọn: nếu các đội có thể ở phiên bản khác nhau cùng lúc, Anh/Chị cần semver đầy đủ.
Migration guide và codemod: hỗ trợ thực tế cho đội sản phẩm
Migration guide (hướng dẫn nâng cấp) không cần dài, nhưng phải đủ để người dùng biết chính xác phải làm gì. Mỗi breaking change cần ghi rõ: thay đổi là gì, tại sao thay đổi, và code trước/sau trông như thế nào. Changelog ghi quá kỹ thuật mà đội thiết kế không hiểu tác động với Figma library là lỗi hay gặp, vì hai đội cần đọc cùng một tài liệu mà hiểu đúng phần việc của mình.
Codemod (script tự động chuyển đổi code) đáng đầu tư khi thay đổi có thể tự động hóa hoàn toàn và phạm vi lớn, ví dụ đổi tên toàn bộ token trên hàng trăm file. Với thay đổi nhỏ hoặc cần đánh giá từng trường hợp, migration guide viết tay là đủ và thực ra dễ duy trì hơn.
Hệ thống không có migration guide thực tế là hệ thống các đội không dám nâng cấp.
Nguyên tắc thực hành, Sinh Vũ Studio
Góc nhìn của Sinh Vũ
Sinh Vũ bàn giao design system với versioning và changelog từ ngày đầu, kể cả với scope nhỏ chỉ khoảng 40 component. Lý do đơn giản: thói quen phân loại breaking hay non-breaking khó xây sau khi hệ thống đã chạy, dễ hơn nhiều khi bắt đầu từ commit đầu tiên.
Trong giai đoạn bảo trì sau bàn giao, Sinh Vũ hỗ trợ khách xây thói quen cập nhật changelog kèm phân loại đúng. Với khách chưa có quy trình nào, Sinh Vũ gợi ý bắt đầu bằng file changelog dạng Markdown đơn giản trước khi chuyển sang tooling phức tạp hơn như Changesets, vì điều quan trọng nhất là thói quen ghi chép, không phải công cụ. Figma library cũng cần được version đồng bộ với code: nếu code đang ở v2 mà Figma vẫn phản ánh v1, đội thiết kế và đội kỹ thuật sẽ làm việc trên hai thực tế khác nhau mà không ai nhận ra.
Nguồn tham khảo
Semantic Versioning 2.0.0, Tom Preston-Werner, semver.org. Changesets, công cụ quản lý changelog và versioning. Thực hành tổng hợp từ changelog các design system lớn: Material, Carbon, Primer.
Câu hỏi thường gặp
Breaking change là gì, làm sao phân biệt với thay đổi bình thường?
Breaking change là thay đổi khiến code đang chạy của người dùng bị vỡ nếu nâng cấp mà không sửa gì thêm. Trong design system, các trường hợp phổ biến gồm: đổi tên prop hoặc token, bỏ hẳn một component hay variant, thay đổi hành vi mặc định không tương thích, thay đổi cấu trúc DOM hoặc CSS class đang được override từ bên ngoài. Nếu người dùng có thể nâng cấp mà không cần chỉnh file nào thì đó không phải breaking change.
Khi nào cần viết codemod, khi nào migration guide thủ công là đủ?
Codemod (script tự động chuyển đổi code) đáng đầu tư khi thay đổi có thể tự động hóa hoàn toàn và phạm vi lớn, ví dụ đổi tên toàn bộ token từ hệ đặt tên cũ sang hệ mới trên hàng trăm file. Nếu thay đổi nhỏ, chỉ ảnh hưởng vài component hoặc cần đánh giá từng trường hợp, migration guide viết tay kèm ví dụ trước và sau là đủ. Đừng đầu tư codemod cho thay đổi chỉ xảy ra một lần và phạm vi hẹp.