md-vector-db/CONTRIBUTING.md

贡献指南

开发环境

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

运行基准测试

uv sync --extra bench
uv run pytest tests/benchmarks/ -v --benchmark-only