Document changes

[dangquangminh]

Mỗi lần Release phần mềm, điều gì khiến người dùng và đội vận hành quan tâm nhất?


Không chỉ là phiên bản mới có tính năng gì, mà còn là:

• Điều gì đã thay đổi?
• Tại sao lại thay đổi?
• Những lỗi nào đã được sửa?
• Có vấn đề bảo mật nào đã được khắc phục không?
• Có tính năng nào sắp bị loại bỏ?

Đó chính là lý do Changelog (CHANGELOG.md) trở thành một tài liệu quan trọng trong quy trình phát triển phần mềm, DevOps và vận hành sản phẩm. Documenting Changes – Ghi nhận các thay đổi của phần mềm


Khi một phiên bản phần mềm mới được phát hành, người dùng cuối và tất cả những người tham gia dự án đều muốn biết lý do và cách thức các thay đổi được thực hiện. Một trong những trách nhiệm của nhà phát triển là ghi lại các thay đổi đã được thực hiện trong từng phiên bản của dự án.

Tệp changelog đóng vai trò quan trọng trong toàn bộ quá trình phát triển và bảo trì phần mềm, thậm chí còn ảnh hưởng đến nhiều quy trình kinh doanh khác. Changelog nên chứa những gì?


Tệp changelog nên bao gồm:

• Tất cả các phiên bản phát hành (release versions)
• Danh sách được sắp xếp theo trình tự thời gian
• Ngày phát hành chính xác của từng phiên bản
• Thông thường, phiên bản mới nhất được đặt ở đầu tài liệu

Đối với mỗi phiên bản, cần có một danh sách riêng ghi lại những thay đổi quan trọng được thực hiện giữa phiên bản hiện tại và phiên bản trước đó.

Nếu dự án sử dụng Semantic Versioning (SemVer), nên công bố rõ điều này trong tài liệu.

Ví dụ:
This project adheres to Semantic Versioning (SemVer).
Version format: MAJOR.MINOR.PATCH Changelog dành cho con người, không phải máy móc


Một nguyên tắc quan trọng:

Changelog được viết cho con người đọc, không phải cho máy.

Do đó, không nên đưa vào:

• Mô tả kỹ thuật quá dài
• Toàn bộ nội dung commit
• Các thay đổi chi tiết ở mức source code

Thay vào đó, mỗi mục nên ngắn gọn, rõ ràng, giúp người đọc nhanh chóng hiểu được:

• Tính năng mới
• Lỗi đã được sửa
• Mức độ ảnh hưởng
• Phạm vi thay đổi

Ví dụ:
Added:
- Support Multi-Factor Authentication (MFA)
- Added REST API for user profile management

Fixed:
- Fixed login timeout issue on Safari browsers
- Resolved memory leak in background worker

Security:
- Patched CVE-2026-12345 in OpenSSL dependency Phân nhóm thay đổi để tăng khả năng đọc


Các thay đổi không nên được liệt kê ngẫu nhiên hoặc theo trình tự commit.

Thông lệ tốt nhất là chia thành các nhóm sau: Added


Các tính năng mới.

Ví dụ:
Added:
- Kubernetes deployment automation
- Dark mode support

---

Changed


Các chức năng đã được thay đổi hoặc cải tiến.

Ví dụ:
Changed:
- Updated authentication flow to OAuth2
- Improved API response performance

---

Deprecated


Các tính năng sẽ sớm bị loại bỏ.

Ví dụ:
Deprecated:
- Legacy XML API endpoint

---

Removed


Các tính năng đã bị loại bỏ.

Ví dụ:
Removed:
- Support for Python 3.8
- Old LDAP authentication module

---

Fixed


Các lỗi đã được sửa.

Ví dụ:
Fixed:
- Fixed race condition in job scheduler
- Corrected timezone conversion issue

---

Security


Các bản vá liên quan đến bảo mật.

Ví dụ:
Security:
- Fixed privilege escalation vulnerability
- Updated vulnerable Log4j dependency Changelog không phải nơi để điều tra chi tiết thay đổi


Nếu đội phát triển hoặc vận hành cần truy vết:

• Ai thực hiện thay đổi?
• Thay đổi chính xác dòng code nào?
• Thời gian commit?
• Commit message?
• Pull Request liên quan?
• Ticket Jira hoặc Issue ID?

Thì changelog không phải nơi phù hợp để tìm kiếm.

Changelog chỉ là:

Một báo cáo tóm tắt (Summary Report).

Các thông tin chi tiết nên được lưu trong:

• Git Repository
• Source Version Control System (GitHub, GitLab, Bitbucket)
• Issue Tracking System (Jira, Azure DevOps, ServiceNow…)

Ví dụ CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

This project adheres to Semantic Versioning.

## [2.1.0] - 2026-06-18

### Added
- Added MFA authentication
- Added API rate limiting

### Changed
- Improved CI/CD deployment speed

### Fixed
- Fixed token refresh issue

### Security
- Patched OpenSSL CVE-2026-12345

## [2.0.1] - 2026-05-30

### Fixed
- Fixed memory leak in worker process

### Security
- Updated vulnerable container base image Góc nhìn DevOps


Trong các môi trường CI/CD hiện đại, changelog không chỉ phục vụ người dùng cuối mà còn mang lại giá trị lớn cho:

• Release Management
• Change Management
• Incident Response
• Audit & Compliance
• DevSecOps Governance
• SRE Postmortem

Một CHANGELOG.md được duy trì tốt giúp toàn bộ tổ chức nhanh chóng hiểu:

"Phiên bản này có gì mới, điều gì thay đổi và có rủi ro nào cần lưu ý trước khi triển khai vào production."