---
name: rock-docs
description: 为 ROCK 项目管理 Docusaurus 文档版本。支持添加新版本文档、添加 Release Note、管理中英文 i18n 文档。当用户说"添加文档版本"、"发布新版本文档"、"添加 release note"、"rock-docs"或需要操作 docs/ 目录下的版本化文档时使用。
---

# ROCK Docs

管理 ROCK 项目的 Docusaurus 版本化文档。

## 项目背景

- Docusaurus 3.9.x，部署于 `https://alibaba.github.io/ROCK/`
- 语言：英文（默认）+ 中文（zh-Hans）
- `includeCurrentVersion: false`，所有发布内容来自 `versioned_docs/`
- `versions.json` 驱动版本注册，`convertVersionsArrayToObject()` 自动生成配置
- 侧边栏：顶层手动 + 内层 `autogenerated`
- Release Notes 通过 `reverseReleaseNoteSidebars()` 自动倒序排列

## 需要操作的 6 个位置

| # | 操作 | 路径 |
|---|------|------|
| 1 | 创建英文文档目录 | `docs/versioned_docs/version-{NEW}/` |
| 2 | 创建版本侧边栏 | `docs/versioned_sidebars/version-{NEW}-sidebars.json` |
| 3 | 更新版本列表 | `docs/versions.json` |
| 4 | 更新最新版本指向 | `docs/docusaurus.config.js` 中的 `lastVersion` |
| 5 | 创建中文文档目录 | `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/` |
| 6 | 创建中文侧边栏翻译 | `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json` |

## 标准目录结构

```
version-X.Y.x/
├── Getting Started/
├── User Guides/
├── References/
│   ├── api.md
│   └── Python SDK References/
├── Release Notes/
│   ├── index.md
│   └── vX.Y.Z.md
└── overview.md
```

## 执行流程

### Phase 0：版本冲突检测

1. 读取 `docs/versions.json` 获取已有版本列表
2. 从用户输入的版本号推断文档版本号（如 `1.4.5` → `1.4.x`）
3. 如果文档版本已存在，**跳转至「仅添加 Release Note」流程**

#### 仅添加 Release Note 流程

**Step A**：创建英文 Release Note
- 路径：`docs/versioned_docs/version-{EXISTING}/Release Notes/v{VERSION}.md`
- 使用下方英文模板

**Step B**：创建中文 Release Note
- 路径：`docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{EXISTING}/Release Notes/v{VERSION}.md`
- 使用下方中文模板

**Step C**：更新 Release Notes 索引

在英文和中文 `Release Notes/index.md` 的标题行下方第一行插入：
```markdown
* [release v{VERSION}](v{VERSION}.md)
```

完成后跳转至 Phase 5 验证。

---

如果文档版本不存在，继续执行完整流程。

### Phase 1：收集信息

1. **新版本号**：如 `1.4.x`
2. **基础版本**：从哪个版本复制？默认取 `versions.json` 第一项
3. **Release Note**：是否创建？版本号是什么？
4. **是否修改 `lastVersion`**：必须明确告知用户影响后再确认：

   > ⚠️ 修改 `lastVersion` 会改变文档站点默认展示版本。当前为 `{当前 lastVersion}`，修改后为 `{NEW}`。是否确认？

   **不要默认选「是」，等用户明确确认。**

具体版本号（如 `1.4.0`）自动推断为文档版本号（`1.4.x`）。

### Phase 2：创建英文文档

#### Step 1：复制英文文档目录

```bash
cp -r docs/versioned_docs/version-{BASE}/ docs/versioned_docs/version-{NEW}/
```

#### Step 1.5：清理旧版本 Release Notes（仅主版本号变更时）

当主版本号（major.minor）不同时（如 `1.4.x` → `1.5.x`）：

1. 删除 `docs/versioned_docs/version-{NEW}/Release Notes/` 下除 `index.md` 外的所有 `v*.md`
2. 重写 `index.md`：

```markdown
---
sidebar_position: 1
---
# Release Notes
```

#### Step 2：复制版本侧边栏

```bash
cp docs/versioned_sidebars/version-{BASE}-sidebars.json docs/versioned_sidebars/version-{NEW}-sidebars.json
```

#### Step 3：创建 Release Note（如果需要）

**英文模板** `docs/versioned_docs/version-{NEW}/Release Notes/v{VERSION}.md`：
```markdown
# v{VERSION}

## Release Date
{Mon DD, YYYY}

---

TODO
```

**中文模板** `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/v{VERSION}.md`：
```markdown
# v{VERSION}

## 发布日期
{YYYY} 年 {M} 月 {D} 日

---

TODO
```

#### Step 3.5：更新 Release Notes 索引

在英文 `docs/versioned_docs/version-{NEW}/Release Notes/index.md` 标题行下方第一行插入：
```markdown
* [release v{VERSION}](v{VERSION}.md)
```

### Phase 3：创建中文文档

#### Step 4：复制中文文档目录

```bash
cp -r docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}/ docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/
```

#### Step 4.5：清理中文旧版本 Release Notes（仅主版本号变更时）

与 Step 1.5 同理：
1. 删除 `docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}/Release Notes/` 下除 `index.md` 外的所有 `v*.md`
2. 重写 `index.md`（中文版标题为 `# 版本说明`）：

```markdown
---
sidebar_position: 1
---
# 版本说明
```

#### Step 5：创建中文侧边栏翻译 JSON

```bash
cp docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{BASE}.json docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-{NEW}.json
```

修改新 JSON 文件中的 `version.label`：

```json
{
  "version.label": {
    "message": "{NEW}",
    "description": "The label for version {NEW}"
  }
}
```

### Phase 4：更新配置

#### Step 6：更新 versions.json

在 `docs/versions.json` 数组开头插入 `{NEW}`。

#### Step 7：更新 docusaurus.config.js（仅用户明确确认后）

修改 `docs/docusaurus.config.js` 中的 `lastVersion` 从 `{BASE}` 为 `{NEW}`。用户选择不修改则跳过。

### Phase 5：验证

**Step 8：构建验证**
```bash
cd docs && npm run build
```
构建成功后启动预览：
```bash
cd docs && npm run serve
```
> `npm run serve` 基于构建产物启动，支持中英文切换验证。`npm run start` 仅加载默认语言，无法验证中文。

**Step 9：手动检查清单**

```
✅ 文档验证清单：

英文版本检查：
   □ 版本下拉菜单中是否显示新版本
   □ 默认展示版本是否符合预期
   □ 英文文档页面是否正常渲染
   □ Release Notes 是否按版本号倒序排列
   □ 侧边栏导航是否完整

中文版本检查（右上角语言切换）：
   □ 中文文档页面是否正常显示
   □ 侧边栏分类名称是否正确翻译
   □ Release Notes 内容是否与英文版本对应

后续工作：
   □ 更新新版本英文文档中的具体内容
   □ 更新中文文档翻译内容
   □ 如有 Release Note，补充具体发布内容
```

## 注意事项

- `docs/rock/` 是未发布版本源码，`includeCurrentVersion: false` 不会发布
- `HiddenSidebars` 中的文件会从侧边栏隐藏，但仍可通过直接链接访问
- 详细 i18n 配置、侧边栏管理、翻译流程参见 [references/i18n-guide.md](references/i18n-guide.md)