Versioning Documentation / Quản Lý Phiên Bản

This reference provides detailed guidelines for versioning API documentation and maintaining changelogs.

API Documentation Versioning

Strategy: Use semantic versioning and separate folders for major versions.

docs/en/api/
├── v1/
│   ├── openapi.yaml
│   └── CHANGELOG.md
├── v2/
│   ├── openapi.yaml
│   └── CHANGELOG.md
└── README.md              # Version comparison and migration guides

When to create new version:

Major (v2.0): Breaking changes (removed endpoints, changed response structure)
Minor (v1.1): New features, backward-compatible additions
Patch (v1.0.1): Bug fixes, documentation updates

Changelog Format

Follow Keep a Changelog format:

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.2.0] - 2024-01-18

### Added / Đã Thêm
- **EN**: New endpoint `POST /api/v1/resources/bulk` for batch operations
- **VI**: Endpoint mới `POST /api/v1/resources/bulk` cho thao tác hàng loạt
- **EN**: Support for filtering by date range in list endpoints
- **VI**: Hỗ trợ lọc theo khoảng thời gian trong các endpoint danh sách

### Changed / Đã Thay Đổi
- **EN**: Improved authentication flow to use refresh tokens
- **VI**: Cải thiện luồng xác thực sử dụng refresh token
- **EN**: Updated pagination default from 20 to 10 items per page
- **VI**: Cập nhật phân trang mặc định từ 20 xuống 10 items mỗi trang

### Deprecated / Đã Lỗi Thời
- **EN**: `GET /api/v1/legacy-endpoint` - Use `GET /api/v1/resources` instead. Will be removed in v2.0
- **VI**: `GET /api/v1/legacy-endpoint` - Dùng `GET /api/v1/resources` thay thế. Sẽ xóa ở v2.0

### Removed / Đã Xóa
- **EN**: OAuth1 authentication support (replaced by OAuth2)
- **VI**: Hỗ trợ xác thực OAuth1 (thay bằng OAuth2)

### Fixed / Đã Sửa
- **EN**: Fixed pagination bug where last page returned empty results
- **VI**: Sửa lỗi phân trang khi trang cuối trả về kết quả rỗng
- **EN**: Resolved race condition in concurrent resource updates
- **VI**: Giải quyết race condition khi cập nhật tài nguyên đồng thời

### Security / Bảo Mật
- **EN**: Added rate limiting to prevent brute force attacks
- **VI**: Thêm giới hạn tần suất để ngăn chặn tấn công brute force

## [1.1.0] - 2024-01-10

### Added / Đã Thêm
- Initial release with core CRUD operations
- Phát hành đầu tiên với các thao tác CRUD cơ bản

[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0

Migration Guide Template

# Migration Guide: v1 to v2

## Breaking Changes / Thay Đổi Không Tương Thích

### 1. Authentication Changes / Thay Đổi Xác Thực

**Before (v1):**
```json
POST /auth/login
{
  "username": "user@example.com",
  "password": "password123"
}

After (v2):

POST /v2/auth/login
{
  "email": "user@example.com",
  "password": "password123",
  "deviceId": "optional-device-id"
}

Migration Steps:

Update client to use email field instead of username
Optionally include deviceId for better security tracking

2. Response Format Changes / Thay Đổi Format Response

Before (v1):

{
  "items": [...],
  "total": 100
}

After (v2):

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "totalPages": 10,
    "totalItems": 100
  }
}

Deprecated Features / Tính Năng Lỗi Thời

Feature	Replacement	Removal Date
`/api/v1/users`	`/api/v2/users`	2024-06-01

Timeline / Lộ Trình

2024-01-18: v2.0 released, v1 deprecated
2024-03-01: v1 enters maintenance mode (no new features)
2024-06-01: v1 removed, v2 becomes stable


## Resources

- [Keep a Changelog](https://keepachangelog.com/) - Changelog format standard
- [Semantic Versioning](https://semver.org/) - Version numbering scheme
- [Back to Documentation Skill](../SKILL.md)

4.4 KiB Raw Blame History