Changelog là gì và cách viết để người dùng thật sự đọc (kèm tool miễn phí)
Hầu hết team đều biết nên có changelog, nhưng rất nhiều team bỏ qua vì trang giấy trắng là phần khó nhất. Mình đã làm một tool để bớt phần khó đó, nên trong bài này mình chia sẻ cách mình viết changelog và tool đi kèm. Mình là người làm ReleaseTale, nên bạn cứ đọc với con mắt đó nhé.

Changelog là gì
Changelog là danh sách theo từng phiên bản, có ngày tháng, ghi lại những gì đã thay đổi trong phần mềm của bạn, phiên bản mới nhất ở trên cùng. Người dùng nhìn vào là biết có gì mới, có gì đã sửa và có gì có thể làm hỏng cách họ đang dùng.
Changelog không phải là git log
Commit message được viết cho người bảo trì, trong lúc đang làm, và mô tả code đã đổi thế nào chứ không phải điều gì đã đổi với người dùng. Nó còn lẫn những thứ không ai cần đọc: bump dependency, refactor, sửa typo. Changelog là sản phẩm được biên tập: ai đó phải chọn thay đổi nào quan trọng, nhóm lại và viết bằng ngôn ngữ dễ hiểu.
Cấu trúc nên dùng
Mình dùng định dạng Keep a Changelog: mỗi phiên bản có ngày và các nhóm Added, Changed, Deprecated, Removed, Fixed, Security. Ví dụ:
## [1.2.0] - 2026-11-19
### Added
- Xuất báo cáo ra PDF từ thanh công cụ (#142)
### Fixed
- Đăng nhập không còn bị lặp lại trang login (#139)
Sáu thói quen để changelog dễ đọc
- Viết cho người đọc, không phải cho codebase. "Xuất báo cáo ra PDF" tốt hơn "Add PDF exporter service".
- Nhóm thay đổi theo loại.
- Phiên bản mới nhất ở trên, có ngày theo định dạng ISO
YYYY-MM-DD. - Ghi rõ breaking change và cách xử lý, đặt gần đầu mục.
- Gắn link tới pull request hoặc issue cho ai cần chi tiết.
- Bỏ phần nhiễu: bump dependency, refactor, typo, trừ khi nó đổi hành vi với người dùng.
Tool miễn phí để có bản nháp đầu tiên
Mình làm một trang chạy hoàn toàn trên trình duyệt: dán danh sách commit (ví dụ kết quả của git log --oneline) và nhận ngay một mục changelog theo Keep a Changelog. Nó nhóm các Conventional Commit theo loại và bỏ chore, test, docs, merge commit. Dữ liệu bạn dán không được gửi đi đâu cả.
👉 https://releasetale.com/tools/changelog-formatter?utm_source=viblo&utm_medium=post
Kết quả chỉ là bản nháp. Bạn vẫn cần đọc lại như một khách hàng, gộp các dòng cùng một thay đổi và đưa breaking change lên đầu.
Nếu muốn có cả bản cho người dùng cuối
Changelog cho developer và release notes cho người dùng là hai việc khác nhau. ReleaseTale đọc commit và pull request của một release rồi viết cả hai bản: release notes dễ hiểu cho người dùng và một mục Keep a Changelog cho developer. Bạn chỉnh sửa rồi publish lên trang hosted, popup "What's new" trong sản phẩm, hoặc file Markdown. Có gói Free (3 changelog, không cần thẻ tín dụng).
Mình rất muốn nghe phản hồi: bản nháp tool tạo ra có đủ dùng chưa, và team bạn đang giữ changelog bằng cách nào?
Tài nguyên khác
- Trình kiểm tra CHANGELOG.md miễn phí: dán file changelog của bạn và xem chỗ nào lệch so với định dạng Keep a Changelog (cũng chạy trên trình duyệt, không gửi dữ liệu đi đâu).
- Mẫu CHANGELOG.md cho thư viện, API, web app và ứng dụng di động: mã nguồn mở, copy dùng ngay.
- Hướng dẫn chi tiết bằng tiếng Anh: How to write a changelog
All rights reserved