# MemoryBear RAG Docs · 版本号约定

> 适用范围：`docs/rag/` 下所有文档，含 Markdown / Mermaid / 评分卡 / 模板。

## 1. 版本号格式（语义化）

```
v<MAJOR>.<MINOR>[-RC<N>]
```

- **MAJOR**：架构层重大变化（如 4 大 Protocol 落地、可插拔 VDB 上线、检索范式切换）
- **MINOR**：增量内容更新（新增章节、补图、回填基准、修订错误）
- **-RC\<N\>**：候选发布（Release Candidate）N，用于在所有升版门槛达成前的过渡发布
- **示例**：`v1.0-RC1` → `v1.0-RC2` → `v1.0` → `v1.1` → `v2.0-RC1` → `v2.0`

## 2. 升版触发规则

| 触发器 | 升版动作 |
|---|---|
| Release Gate 全部达成（见 release-manifest） | RCN → 正式版（去掉 -RC 后缀） |
| 单文档 Should-Fix 修订 | 文档级 frontmatter `version` 增加 patch 标识（如 `1.0.1`），全集版本不变 |
| 新增 Sprint 全套文档（如 Sprint-4 立项） | 全集 MINOR +1（v1.1 → v1.2） |
| 4 大 Protocol 落地、可观测性引入、Plugin Registry 上线 | 全集 MAJOR +1（v1.x → v2.0-RC1） |
| 紧急 hot-fix（修正错误源码引用、补救一票否决项） | 单文档 patch +1，并在 INDEX.md 记录 |

## 3. frontmatter 规范

每个 `.md` 文档 **必须**有 frontmatter，包括：

```yaml
---
name: <文档简称>
description: <一句话描述>
type: <user|feedback|project|reference|review|template|...>
sprint: <S1|S2|S3>
task: <T1|T2|...>
author: <责任人角色名>
reviewer: <终审责任人或 "待 [S2-T7] 评审">
version: <语义化版本，如 1.0.0>
source-commit: <锁定的代码 SHA，如 feae2f2e>
last-reviewed-at: <YYYY-MM-DD>
---
```

> **强制项**：name、description、type、source-commit、last-reviewed-at。
> **可选项**：reviewer（评审中的文档可填 "待 [S2-T7] 评审"）、version（占位文档可不填）。

## 4. source-commit 锁定规则

- **每篇深度文档**必须锁定一个具体的 commit SHA，作为"本文档与代码 100% 对齐的时间点"。
- 当 main 分支前进、且与文档相关代码发生变化时：
  - 微改（重命名、注释、格式）→ 不强制更新文档，但可顺手更新 `last-reviewed-at`。
  - 接口变化、流程改动 → **必须**修订文档，并刷新 source-commit 与 last-reviewed-at。
- **多文档共享 commit**：本次全集统一锁定到 `feae2f2e`（基线），若后续文档修订采用新 commit，需在 INDEX.md 标注差异。

## 5. 与代码版本的对齐

| 文档版本 | MemoryBear 代码版本 |
|---|---|
| `v1.0-RCN`（候选） | 基于 `feae2f2e` 工作分支 `agent/ai/f8de881a` |
| `v1.0`（正式） | 与下一个 release tag（如 `v0.4.0`）同步发布 |
| `v1.1` | 与 release `v0.4.x` 增量同步 |
| `v2.0` | 对应 4 大 Protocol 落地之后的 release（预计 `v0.5.0` 之后） |

> 文档版本号**不强制**与代码版本号一致，但发布通告中需明确"对应代码版本"。

## 6. 已废弃文档处理

- 标记 `status: deprecated` 在 frontmatter；
- 文件首部加显眼的 `> ⚠️ DEPRECATED · 自 v1.x 起，本文已并入 <新文档路径>` 横幅；
- 保留 6 个月（覆盖至少一个 release cycle），之后转移到 `docs/rag/_archive/<year>/` 归档。

## 7. 协议变更（如 4 大 Protocol 名称改动）

- 任意涉及命名的协议（Retriever / Reranker / Embedder / Generator / GraphStore）变更，必须同步刷新：
  1. `evolution/architecture-refactor-suggestions.md` 主文
  2. `evolution/future-extensions-roadmap.md` 引用处
  3. `_indexes/glossary.md`
  4. `_indexes/file-index.md` "提议中"行
  5. `INDEX.md` 版本与状态
  6. 所有 Sprint-2 文档中提到该协议的章节
- 变更记录留在 `evolution/CHANGELOG.md`（v1.1 起新建）。

— **Versioning Convention · v1.0-RC1 · 2026-05-08** —