feat: 第三优先级完善 — CI/CD、PyPI、pre-commit、CHANGELOG、贡献指南、基准测试、ADR

2026-07-11 20:13:36 +08:00
parent 7e0b9553c8
commit 2ddb6de92f
13 changed files with 483 additions and 12 deletions
@@ -0,0 +1,54 @@
+# 贡献指南
+
+## 开发环境
+
+```bash
+git clone git@github.com:LHY0125/md-vector-db.git
+cd md-vector-db
+uv sync --extra dev --extra all
+uv run pre-commit install
+```
+
+## 开发流程
+
+1. **Fork 仓库** → 创建功能分支 `feat/xxx`
+2. **写测试**（TDD）: 先在 `tests/` 下写失败测试
+3. **实现功能**: 最少代码让测试通过
+4. **运行全部测试**: `uv run pytest tests/ --cov=src -v`
+5. **确保覆盖率 ≥ 80%**: `uv run pytest tests/ --cov=src --cov-fail-under=80`
+6. **Lint 检查**: `uv run ruff check src/ tests/`
+7. **类型检查**: `uv run mypy src/ --ignore-missing-imports`
+8. **提交**: 遵循约定式提交格式
+9. **创建 PR**: 描述清楚变更内容和测试结果
+
+## 提交消息格式
+
+```
+<类型>: <描述>
+
+<可选正文>
+```
+
+类型: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`
+
+## 代码风格
+
+- Python 3.13+，遵循 PEP 8
+- 类型注解覆盖所有 public API
+- 中文注释
+- 小文件原则（<800 行），函数 <50 行
+
+## 添加新文档格式支持
+
+1. 在 `src/core/splitters/` 下实现 Splitter Protocol
+2. 在 `src/core/splitters/registry.py` 注册扩展名
+3. 在 `pyproject.toml` 添加可选依赖
+4. 在 `tests/` 下添加测试
+5. 更新 `README.md`
+
+## 运行基准测试
+
+```bash
+uv sync --extra bench
+uv run pytest tests/benchmarks/ -v --benchmark-only
+```