贡献

贡献

我们欢迎各种贡献！Leann 是由社区打造、为社区服务的。

贡献方式

• Bug 报告：发现问题了吗？告诉我们吧！
• 功能请求：有好点子吗？我们很乐意听听！
• 代码贡献：欢迎各水平的 PR！
• 文档：帮助让 Leann 更易用！
• 基准测试：分享你的性能结果！

开发环境搭建

前提条件

1. 安装 uv（快速的 Python 包管理器）：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   ​

2. 克隆仓库：

   git clone https://github.com/LEANN-RAG/LEANN-RAG.git
   cd LEANN-RAG
   ​

3. 安装系统依赖：

   macOS：

   brew install llvm libomp boost protobuf zeromq pkgconf
   ​

   Ubuntu/Debian：

   sudo apt-get install libomp-dev libboost-all-dev protobuf-compiler \
                        libabsl-dev libmkl-full-dev libaio-dev libzmq3-dev
   ​

4. 从源码构建：

   # macOS
   CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ uv sync
   
   # Ubuntu/Debian
   uv sync
   ​

预提交钩子

我们使用预提交钩子来确保代码质量和一致性。每次提交前都会自动运行这些钩子。

设置预提交

1. 安装预提交工具：

   uv sync lint
   ​

2. 安装 Git 钩子：

   pre-commit install
   ​

3. 手动运行预提交（可选）：

   uv run pre-commit run --all-files
   ​

预提交检查

我们的预提交配置包括：

• 移除尾随空格
• 修复文件末尾
• YAML 校验
• 防止大文件
• 检测合并冲突
• 检测调试语句
• 使用 ruff 格式化代码
• 使用 ruff 检查代码风格

测试

运行测试

# Install test tools only (no project runtime)
uv sync --group test

# Run all tests
uv run pytest

# Run specific test file
uv run pytest test/test_filename.py

# Run with coverage
uv run pytest --cov=leann
​

编写测试

• 将测试放在 test/ directory
• Follow the naming convention test_*.py
• Use descriptive test names that explain what's being tested
• Include both positive and negative test cases

Code Style

We use ruff 中，以同时进行代码风格检查和格式化，确保代码风格一致。

格式化你的代码

# Format all files
ruff format

# Check formatting without changing files
ruff format --check
​

检查代码风格

# Run linter with auto-fix
ruff check --fix

# Just check without fixing
ruff check
​

风格指南

• 遵循 PEP 8 规范
• 使用描述性的变量名
• 在适当的地方添加类型注解
• 为所有公共函数和类编写文档字符串
• 保持函数专注且单一职责

CI/CD

我们的 CI 管道会自动运行于所有拉取请求中。它包括：

1. 代码风格检查与格式化：确保代码符合我们的风格规范
2. 多平台构建：在 Ubuntu 和 macOS 上测试
3. Python 版本矩阵：在 Python 3.9 到 3.13 上测试
4. 生成 wheel 包：确保包可以构建并分发

CI 命令

CI 使用与预提交相同的命令，以保证一致性：

# Linting
ruff check .

# Format checking
ruff format --check .
​

请务必在推送之前本地通过这些检查！

拉取请求流程

1. fork 仓库并从 main 创建你的分支：

   git checkout -b feature/your-feature-name
   ​

2. 进行修改：

   • 编写清晰、有文档的代码
   • 为新功能添加测试
   • 根据需要更新文档

3. 运行预提交检查：

   pre-commit run --all-files
   ​

4. 测试你的修改：

   uv run pytest
   ​

5. 提交时使用描述性信息：

   git commit -m "feat: add new search algorithm"
   ​

   遵循 Conventional Commits 规范：

   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
   • test: for test additions/changes
   • refactor: for code refactoring
   • perf: for performance improvements

6. Push and create a pull request:

   • Provide a clear description of your changes
   • Reference any related issues
   • Include examples or screenshots if applicable

Documentation

When adding new features or making significant changes:

1. Update relevant documentation in /docs
2. 为新函数/类添加文档字符串
3. 如需，更新 README.md
4. 包含使用示例

获取帮助

• Discord：加入我们的社区进行讨论
• 问题：查看已有问题或创建新问题
• 讨论：针对一般性问题和想法

许可协议

通过贡献，你同意你的贡献将采用与项目相同的许可协议（MIT）。

感谢你为 LEANN 做出贡献！无论贡献大小，每一份努力都在让项目变得更好，造福所有人。

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文的母语文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。