# Một bản vá cho một khách có thể làm hỏng ba khách khác

> Semver, changelog và cửa sổ bảo trì là ba công cụ giúp mỗi khách hàng biết trước lúc nào được nâng cấp và sẽ có gì thay đổi.

Bản gốc: https://fdetimes.net/vi/bach-khoa/semver-changelog-cap-nhat-nhieu-khach/

Thứ Sáu, bạn sửa một lỗi múi giờ trong connector cho khách A. Bản vá nhỏ, test đều xanh, bạn đẩy lên cho cả năm khách đang dùng chung connector. Sáng thứ Hai có ba ticket: báo cáo của khách B lệch một ngày, pipeline của khách C báo lỗi parse, còn khách D hỏi sao không ai báo trước.

Code không có lỗi. Cái sai là quy trình phát hành chưa tính đến chuyện một thay đổi đi tới nhiều khách, mỗi khách một nhịp vận hành và một mức chịu rủi ro khác nhau.

Với FDE, chuyện này xảy ra sớm hơn nhiều người nghĩ. Khi một tích hợp bạn viết cho khách đầu tiên được đem sang khách thứ hai và thứ ba, bạn đã thành người bảo trì một sản phẩm, dù chưa ai gọi nó là sản phẩm. Ba công cụ cần nắm là số phiên bản, changelog và cửa sổ bảo trì.

## Số phiên bản là lời hứa, không phải số thứ tự

Semantic Versioning 2.0.0 định nghĩa ba con số với ba ý nghĩa. Tăng MAJOR khi có thay đổi API không tương thích. Tăng MINOR khi thêm tính năng mà vẫn tương thích ngược. Tăng PATCH khi sửa lỗi mà vẫn tương thích ngược.

Chỗ khó là chữ "tương thích" phải hiểu theo góc nhìn của khách. Thử áp vào connector ở trên, phiên bản hiện tại là 2.3.1:

| Thay đổi | Khách thấy gì | Phiên bản mới |
|---|---|---|
| Sửa lỗi crash khi file rỗng | Cái vốn hỏng nay chạy được | 2.3.2 |
| Thêm trường tùy chọn `region` | Có thêm dữ liệu, cái cũ giữ nguyên | 2.4.0 |
| Đổi `customer_id` thành `account_id` | Truy vấn đang chạy bị gãy | 3.0.0 |
| Đổi timestamp từ giờ địa phương sang UTC | Cùng trường nhưng giá trị khác | 3.0.0 |

Dòng cuối chính là bản vá thứ Sáu. Trong mắt bạn đó là sửa lỗi, nhưng khách B đã viết báo cáo dựa trên hành vi cũ. Khi một thay đổi làm khác đi kết quả mà khách đang dùng, cách an toàn là coi nó là MAJOR, hoặc thêm một cờ cấu hình để khách tự bật hành vi mới.

SemVer còn một quy tắc mà nhiều đội hay quên: một phiên bản đã phát hành thì không được sửa nội dung, sửa gì cũng phải ra phiên bản mới.

Khi nhiều khách cùng ghim 2.3.1, lặng lẽ build lại rồi gắn đè tag 2.3.1 nghĩa là hai khách cùng chạy "2.3.1" nhưng chạy hai thứ khác nhau.

Lúc có sự cố, bạn sẽ không còn biết ai đang chạy gì.

**Điểm mấu chốt:** Số phiên bản là lời hứa với khách, không phải nhãn đội mình dán cho tiện.

## Để mỗi khách tự chọn ngày nâng cấp

Stripe là ví dụ đáng học. Lần đầu một tài khoản gọi API, tài khoản đó được ghim vào phiên bản mới nhất lúc ấy. Sau đó khách nâng cấp theo lịch của mình chứ không theo lịch của Stripe.

Phía sau, mỗi thay đổi không tương thích ngược được gói trong một version change module. Nhờ vậy các phiên bản cũ vẫn chạy được mà logic tương thích không lan khắp codebase.

Stripe hiện phát hành phiên bản mới hằng tháng không kèm thay đổi phá vỡ, và mỗi năm hai lần ra một bản major có thay đổi phá vỡ. Webhook endpoint cũng ghim được phiên bản riêng, nên một khách có thể nâng cấp từng tích hợp một.

Một FDE bảo trì connector cho vài khách thì không cần dựng cả một hệ thống như vậy. Mỗi khách có một dòng cấu hình ghi phiên bản họ đang chạy là đủ.

Khi đổi `customer_id` thành `account_id`, đừng rải `if version < 3` khắp nơi mà viết một hàm adapter duy nhất chuyển định dạng mới về định dạng cũ cho khách còn ở 2.x.

Đến ngày bỏ hỗ trợ 2.x, bạn chỉ cần xóa đúng một file.

## Nói rõ bạn còn hỗ trợ đến đâu

Ghim phiên bản mà không có giới hạn thì bạn sẽ phải nuôi mười phiên bản cùng lúc. Kubernetes giải quyết bằng một chính sách công khai: kubelet được phép cũ hơn kube-apiserver tối đa ba phiên bản minor. Release branch chỉ được giữ cho ba bản minor gần nhất, và từ 1.19 trở đi mỗi bản có khoảng một năm vá lỗi.

Nhờ con số đó, khách biết mình có bao nhiêu thời gian và có thể nâng cấp từng phần thay vì phải đổi tất cả trong một đêm.

Bạn nên viết một đoạn tương tự cho connector của mình, chẳng hạn: "Vá lỗi bảo mật cho bản minor hiện tại và hai bản trước đó; bản major cũ được hỗ trợ sáu tháng sau khi bản mới ra." Con số cụ thể tùy đội bạn quyết, miễn là nó được ghi ra giấy và khách đã đọc.

## Changelog viết cho người vận hành phía khách

Keep a Changelog mở đầu bằng một nguyên tắc: changelog là để người đọc, không phải để máy đọc. Dán nguyên `git log` vào không phải là changelog. Người đọc ở đây là kỹ sư vận hành phía khách, và họ chỉ cần biết hai điều: có cần làm gì không, và làm trước ngày nào.

Chuẩn này chia thay đổi thành các nhóm cố định, trong đó có Deprecated cho tính năng sắp bị bỏ và Removed cho tính năng đã bỏ. Họ cũng nói rõ mức tối thiểu: nếu không làm gì khác, ít nhất hãy liệt kê deprecation, những gì đã gỡ bỏ và mọi thay đổi phá vỡ. Với connector ở trên, một mục changelog tốt trông như sau:

```markdown
## [3.0.0] - 2026-12-01
### Changed
- BREAKING: `customer_id` đổi tên thành `account_id`.
  Việc cần làm: sửa truy vấn đọc trường này. Bản 2.x vẫn được vá lỗi đến 2027-06-01.
- BREAKING: timestamp trả về theo UTC thay vì giờ địa phương.
### Deprecated
- Tham số `legacy_auth`, sẽ bị gỡ ở 4.0.0.
### Fixed
- Không còn crash khi file đầu vào rỗng.
```

Mỗi dòng BREAKING đều đi kèm việc khách cần làm và một hạn chót. Nếu khách D đọc được một mục như vậy trước thứ Sáu thì đã không có ticket thứ ba.

## Cửa sổ bảo trì chỉ quy định giờ bắt đầu

Phần cuối là thời điểm triển khai. Amazon RDS dùng cửa sổ bảo trì 30 phút mỗi tuần. Nếu bạn không chọn, RDS sẽ tự gán một ngày ngẫu nhiên trong tuần. Tài liệu của AWS cũng ghi rõ công việc bảo trì không chắc xong trước khi cửa sổ đóng và có thể chạy quá giờ kết thúc.

Thử hình dung khách C cho bạn cửa sổ từ 02:00 đến 02:30 sáng Chủ nhật. Trên staging, bước migration đổi tên trường mất 40 phút. Nếu chạy đúng như kế hoạch thì đến 02:40 hệ thống vẫn đang dở việc trong khi ca trực phía khách đã về.

Có hai cách hợp lý: xin cửa sổ dài hơn, hoặc tách migration thành bước chạy nền trước đó vài ngày, để trong cửa sổ chỉ còn việc chuyển cờ.

RDS còn một chi tiết nên học theo. Với nâng cấp bắt buộc, sau ngày áp dụng bắt buộc RDS vẫn có thể nâng cấp ngoài cửa sổ khách đã chọn. Dời cửa sổ không có nghĩa là hoãn được mãi. Khi bỏ hỗ trợ 2.x, bạn cũng cần một ngày như vậy, báo cho khách từ sớm và nhắc lại trong changelog.

## Những lỗi hay gặp nhất

Lỗi phổ biến nhất là phân loại theo kích thước diff thay vì theo tác động lên khách, như bản vá UTC ở đầu bài. Lỗi thứ hai là gắn đè tag cũ cho nhanh, đúng điều SemVer cấm. Lỗi thứ ba là coi giờ đóng cửa sổ bảo trì là giờ chắc chắn xong việc, nên không có ai trực khi công việc chạy quá giờ.

Lỗi thứ tư ít người để ý: deploy cho cả năm khách cùng lúc. Nên có thứ tự, bắt đầu từ khách chịu được rủi ro cao nhất hoặc môi trường staging của khách, chờ một chu kỳ dữ liệu chạy xong rồi mới đẩy tiếp.

## Đưa kỹ năng này vào CV và phỏng vấn

Câu "bảo trì một connector có phiên bản cho nhiều khách, có chính sách hỗ trợ và changelog công khai" trong CV cho nhà tuyển dụng thấy bạn từng gánh hậu quả của chính code mình viết. Nếu có thể, hãy dẫn link tới changelog hoặc trang chính sách hỗ trợ đó.

Khi đọc tin tuyển FDE, bạn nên để ý những cụm như "rollout", "upgrade" hay "multi-tenant", rồi hỏi lại trong phỏng vấn xem đội đang phát hành cho bao nhiêu khách và theo nhịp nào. Kể lại một lần bạn xếp nhầm một thay đổi vào PATCH và sau đó đã sửa quy trình ra sao thường thuyết phục hơn mọi định nghĩa.

Khách không đòi hỏi bạn không bao giờ sai. Họ cần biết trước lúc nào bạn sẽ thay đổi điều gì, và khi lỡ có sai sót thì có đường để quay về bản cũ.

**Thử ngay tuần này:**

- Lấy 10 commit gần nhất của một connector hay SDK bạn đang bảo trì, xếp từng commit vào MAJOR, MINOR hoặc PATCH rồi đối chiếu với số phiên bản đã phát hành
- Viết lại changelog của bản phát hành gần nhất theo các mục Added, Changed, Deprecated, Removed, Fixed, đưa mục Deprecated và Removed lên đầu
- Viết một chính sách hỗ trợ phiên bản dài một đoạn, nói rõ bạn còn vá lỗi cho những bản nào và đến bao giờ, rồi gửi trưởng nhóm góp ý

## Nguồn

- [Semantic Versioning 2.0.0](https://semver.org/)

- [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)

- [APIs as infrastructure: future-proofing Stripe with versioning](https://stripe.com/blog/api-versioning)

- [How API versioning works](https://docs.stripe.com/api-versions)

- [Version Skew Policy](https://kubernetes.io/releases/version-skew-policy/)

- [Maintaining a DB instance - Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html)
