Đọc changelog/migration guide khi nâng cấp ROS2

Hai bài trước đã bàn cách đọc README và design doc. Có một loại tài liệu khác dễ bị bỏ qua nhất, nhưng lại là nguyên nhân phổ biến của lỗi "nâng cấp xong tự nhiên hành vi khác lạ" — CHANGELOG và migration guide.

Khái niệm chính

CHANGELOG là file (thường CHANGELOG.md hoặc CHANGELOG.rst ở gốc repo) liệt kê thay đổi giữa các phiên bản, thường phân loại theo: Added (tính năng mới), Changed (thay đổi hành vi có sẵn), Deprecated (sắp bị loại bỏ), Removed/Breaking (đã loại bỏ, không tương thích ngược). Migration guide là tài liệu riêng (nếu có) tổng hợp sẵn các bước cần làm khi nâng cấp qua một mốc phiên bản lớn — không phải mọi package đều có, nhưng khi có thì đáng tin cậy hơn tự suy luận từ changelog thô.

Nguyên lý hoạt động

Khi nâng cấp qua nhiều phiên bản cùng lúc (VD: từ v1.2 lên v2.0, bỏ qua v1.3, v1.4...), cần đọc CẢ CHUỖI changelog của mọi phiên bản trung gian, không chỉ dòng mới nhất — một thay đổi "Changed" ở phiên bản trung gian (VD: đổi tên tham số) có thể không được nhắc lại ở phiên bản cuối, nhưng vẫn ảnh hưởng trực tiếp tới cấu hình cũ. Đây là lý do lỗi nâng cấp thường mang tính chất "silent failure" — hệ thống vẫn chạy, không báo lỗi, nhưng tham số cấu hình cũ không còn tác dụng vì tên đã đổi ở một phiên bản trung gian nào đó.

Tóm lại: Đọc changelog TRƯỚC khi nâng cấp là thói quen phòng ngừa; đọc SAU khi gặp lỗi lạ là thói quen chữa cháy — cùng một tài liệu, nhưng chi phí thời gian debug chênh lệch rất lớn giữa hai cách tiếp cận. Đặc biệt quan trọng với các dòng đánh dấu Breaking Change, cần xử lý bắt buộc trước khi nâng cấp, không phải tuỳ chọn.

Kiến thức kỹ thuật

Thông số

Loại thay đổi	Mức độ cần quan tâm
Added	Thấp — tính năng mới, không ảnh hưởng cấu hình cũ
Changed	Trung bình — có thể ảnh hưởng hành vi/tên tham số cũ, cần đọc kỹ
Deprecated	Trung bình-cao — vẫn hoạt động nhưng nên chuyển sang cách mới sớm
Removed / Breaking Change	Cao nhất — bắt buộc phải sửa cấu hình/code trước khi nâng cấp, nếu không hệ thống sẽ lỗi hoặc im lặng mất chức năng

Ứng dụng thực tế

Khi nâng cấp một AMR đang chạy ROS2 Humble lên phiên bản mới hơn (Iron/Jazzy), các package cốt lõi như Nav2, robot_localization, slam_toolbox (đã học xuyên suốt chuyên mục ROS2 Navigation) đều có CHANGELOG riêng cần đọc trước — một tham số cấu hình costmap đã hoạt động ổn định qua nhiều tháng có thể đổi tên hoặc đổi hành vi mặc định ở phiên bản mới, và nếu không đọc changelog trước, robot có thể vận hành với costmap không đúng như thiết kế ban đầu mà không có cảnh báo lỗi rõ ràng nào — nguy hiểm hơn nhiều so với lỗi build rõ ràng ngay khi biên dịch.

Ví dụ thực tế

Kịch bản: nâng cấp package Nav2 từ phiên bản cũ lên phiên bản mới hơn 2 bậc,
robot sau nâng cấp vẫn chạy nhưng costmap có vẻ "quá thận trọng" so với trước

Quy trình debug đúng — đọc changelog CẢ 3 phiên bản trung gian đã bỏ qua:

Phiên bản trung gian 1: "Added: tham số mới inflate_unknown (mặc định false)"
Phiên bản trung gian 2: "Changed: giá trị mặc định inflate_unknown đổi thành true"
Phiên bản đích:          không nhắc lại thay đổi này (đã "cũ" từ góc nhìn changelog mới nhất)

Nguyên nhân xác định: giá trị mặc định của inflate_unknown đã âm thầm đổi
ở phiên bản trung gian, khiến vùng "unknown" trên bản đồ giờ cũng được
tính vào inflation layer — đúng nguyên nhân robot "quá thận trọng"

Nếu chỉ đọc changelog phiên bản đích (không đọc phiên bản trung gian),
sẽ không bao giờ tìm ra nguyên nhân này

Lỗi thường gặp

• Chỉ đọc changelog phiên bản đích khi nâng cấp qua nhiều bậc — như ví dụ trên, bỏ lỡ thay đổi ở phiên bản trung gian dù vẫn ảnh hưởng trực tiếp hệ thống hiện tại.
• Đọc changelog sau khi gặp lỗi thay vì trước khi nâng cấp — như đã nêu, cùng tài liệu nhưng chi phí debug chênh lệch lớn giữa hai thời điểm đọc.
• Bỏ qua dòng Deprecated vì "vẫn hoạt động" — tính năng deprecated thường bị xoá hẳn ở phiên bản lớn tiếp theo, trì hoãn xử lý dồn nợ kỹ thuật cho lần nâng cấp sau, thường khó xử lý hơn nhiều do dồn nhiều thay đổi cùng lúc.
• Không phân biệt "Breaking Change" với thay đổi thông thường — một số changelog không phân loại rõ ràng, cần đọc kỹ mô tả để tự đánh giá mức độ ảnh hưởng, không chỉ lướt qua tiêu đề.

Kết luận

CHANGELOG và migration guide là tài liệu phòng ngừa, hiệu quả nhất khi đọc trước khi nâng cấp — đặc biệt cần đọc cả chuỗi phiên bản trung gian khi nâng cấp qua nhiều bậc cùng lúc, không chỉ phiên bản đích. Lỗi "silent failure" sau nâng cấp thường có nguồn gốc từ đây, khó chẩn đoán hơn nhiều so với lỗi build rõ ràng. Bài cuối cùng của chuyên mục Tài liệu mã nguồn mở đi vào cách đánh giá độ tin cậy của một repo mã nguồn mở trước khi quyết định phụ thuộc vào nó cho dự án dài hạn.