# Changelogs 目录说明

本目录存放 monSQLize 各版本的详细变更文档。

---

## 📁 目录结构

```
changelogs/
├── README.md           # 本说明文档
├── TEMPLATE.md         # 变更文档模板
├── v3.0.0.md          # v3.0.0 Major 稳定版详细变更
├── v2.0.7.md          # 从未发布的候选归档
├── v2.0.6.md          # v2.0.6 详细变更
├── v2.0.5.md          # v2.0.5 详细变更
├── v2.0.4.md          # v2.0.4 详细变更
├── v2.0.3.md          # v2.0.3 详细变更
├── v2.0.2.md          # v2.0.2 详细变更
├── v2.0.1.md          # v2.0.1 详细变更
├── v2.0.0.md          # v2.0.0 详细变更
└── v1.x.y.md          # 历史版本详细变更（仓库归档）
```

---

## 📝 文档格式

每个版本的详细变更文档包含以下章节：

### 必需章节

1. **版本信息** - 版本号、日期、类型、风险级别、兼容性
2. **变更摘要** - 一句话总结变更核心内容
3. **背景说明** - 为什么需要这次变更
4. **变更内容** - 改了什么
5. **影响范围** - 影响哪些文件和功能
6. **详细变更清单** - Added/Changed/Fixed 等分类列表
7. **验证方法** - 如何验证变更

### 可选章节

- **迁移指南** - 如何升级/降级（如有破坏性变更）
- **相关资源** - 文档/示例/测试链接
- **设计决策** - 为什么这样设计
- **未来改进** - 计划的后续改进

---

## 🔍 快速查找

### 按版本类型

- **未发布归档**: v2.0.7
- **正式发布**: v3.0.0, v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1, v2.0.0, v1.0.0
- **功能版本**: v1.x
- **修复版本**: v1.x.y

### 按功能领域

- **TypeScript 生产运行时与 v1 平滑升级**: v3.0.0, v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1, v2.0.0
- **实时监听 / 管理功能 / 核心功能**: v1.x 历史版本

### 按风险级别

- **P0 (Critical)**: v2.0.0
- **Major**: v3.0.0
- **Patch**: v2.0.6, v2.0.5, v2.0.4, v2.0.3, v2.0.2, v2.0.1
- **P1 (High)**: v1.x 破坏性或高风险历史版本
- **P2 (Low)**: v1.x 修复版本

---

## ✍️ 如何创建新的变更文档

### 步骤1: 复制模板

```bash
cp TEMPLATE.md v{版本号}.md
```

### 步骤2: 填写内容

根据模板章节填写变更信息：
- 版本信息
- 变更摘要
- 背景说明
- 变更内容
- 影响范围
- 详细变更清单
- 验证方法

### 步骤3: 更新主 CHANGELOG

在项目根目录的 `CHANGELOG.md` 中：
- 在"版本概览"表格最上方添加新行
- 格式：版本列和详情列指向当前发布版本的 `changelogs/v{版本号}.md`

### 步骤4: 提交变更

```bash
git add CHANGELOG.md changelogs/v{版本号}.md
git commit -m "docs: 发布 v{版本号}"
git tag v{版本号}
git push origin main --tags
```

---

## 📚 模板说明

### TEMPLATE.md

`TEMPLATE.md` 是创建新版本文档的标准模板，包含：

- 完整的章节结构
- 占位符和示例
- 注释说明
- Markdown 格式规范

使用时请：
1. 复制模板文件
2. 重命名为对应版本号
3. 替换所有占位符
4. 删除不需要的可选章节
5. 补充完整的变更信息

---

## 📊 版本命名规范

遵循[语义化版本](https://semver.org/lang/zh-CN/)：

### 格式: vMAJOR.MINOR.PATCH

- **MAJOR** - 不兼容的 API 变更
- **MINOR** - 向后兼容的新增功能
- **PATCH** - 向后兼容的问题修复

### 示例

- `v1.0.0` - 正式发布
- `v1.1.0` - 新增功能
- `v1.1.1` - Bug 修复
- `v2.0.0` - 破坏性变更

---

## 🔗 相关资源

- **主 CHANGELOG**: [../CHANGELOG.md](../CHANGELOG.md)
- **项目文档**: [GitHub docs](https://github.com/vextjs/monSQLize/tree/main/docs)
- **使用示例**: [GitHub examples](https://github.com/vextjs/monSQLize/tree/main/examples)
- **测试用例**: [GitHub test](https://github.com/vextjs/monSQLize/tree/main/test)
- **语义化版本**: https://semver.org/lang/zh-CN/

---

## 📋 变更文档清单

| 版本 | 文件 | 状态 | 发布日期 |
|------|------|------|---------|
| v3.0.0 | v3.0.0.md | ✅ 已发布 | 2026-07-14 |
| v2.0.7 | v2.0.7.md | 未发布归档 | - |
| v2.0.6 | v2.0.6.md | ✅ 已发布 | 2026-06-15 |
| v2.0.5 | v2.0.5.md | ✅ 已发布 | 2026-06-13 |
| v2.0.4 | v2.0.4.md | ✅ 已发布 | 2026-06-12 |
| v2.0.3 | v2.0.3.md | ✅ 已发布 | 2026-06-11 |
| v2.0.2 | v2.0.2.md | ✅ 已发布 | 2026-06-09 |
| v2.0.1 | v2.0.1.md | ✅ 已发布 | 2026-06-03 |
| v2.0.0 | v2.0.0.md | ✅ 已发布 | 2026-06-01 |
| v1.x | 仓库历史归档 | ✅ 已发布 | 2025-12-03 起 |

---

**目录版本**: 2.0
**最后更新**: 2026-07-10
**维护者**: monSQLize Team