# 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](https://keepachangelog.com/) format:

```markdown
# 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

```markdown
# 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):**
```json
POST /v2/auth/login
{
  "email": "user@example.com",
  "password": "password123",
  "deviceId": "optional-device-id"
}
```

**Migration Steps:**
1. Update client to use `email` field instead of `username`
2. Optionally include `deviceId` for better security tracking

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

**Before (v1):**
```json
{
  "items": [...],
  "total": 100
}
```

**After (v2):**
```json
{
  "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)
