贡献指南¶
感谢您对Symphra Excel的关注！我们欢迎所有形式的贡献。
贡献方式¶
您可以通过以下方式为项目做出贡献：
- 🐛 报告Bug - 发现问题并报告
- 💡 提出建议 - 分享您的想法和需求
- 📝 改进文档 - 修正错误或补充内容
- 💻 贡献代码 - 修复Bug或添加新功能
- 🌍 翻译 - 帮助翻译文档
- ⭐ 推广 - 向他人推荐项目
开始之前¶
环境准备¶
- Fork项目
访问 https://github.com/getaix/symphra-excel 并点击Fork。
- 克隆仓库
- 创建虚拟环境
- 安装依赖
- 验证安装
报告问题¶
报告Bug¶
在提交Bug报告前，请：
- 搜索现有Issues确认问题未被报告
- 使用最新版本重现问题
- 收集必要的信息
Bug报告模板:
## Bug描述
[简短描述问题]
## 复现步骤
1. 步骤1
2. 步骤2
3. ...
## 期望行为
[描述您期望的行为]
## 实际行为
[描述实际发生的情况]
## 环境信息
- Python版本: 3.11
- Symphra Excel版本: 0.1.0
- 操作系统: macOS 14.0
## 复现代码
```python
from symphra_excel import Workbook
# 您的代码
\```
## 错误信息
\```
完整的错误堆栈
\```
\```
### 功能请求
**功能请求模板**:
```markdown
## 功能描述
[描述您想要的功能]
## 使用场景
[说明为什么需要这个功能]
## 期望的API
```python
# 示例代码展示您期望的用法
\```
## 替代方案
[是否有其他解决方案]
\```
## 贡献代码
### 工作流程
1. **创建分支**
```bash
git checkout -b feature/my-feature
# 或
git checkout -b fix/my-bugfix
-
进行修改
-
编写代码
- 添加测试
-
更新文档
-
运行测试
# 运行所有测试
pytest
# 运行特定测试
pytest tests/test_workbook.py
# 检查覆盖率
pytest --cov=symphra_excel --cov-report=html
- 代码检查
# 格式化代码
black symphra_excel tests
# 排序导入
isort symphra_excel tests
# 代码检查
flake8 symphra_excel tests
# 类型检查
mypy symphra_excel
- 提交更改
- 推送分支
- 创建Pull Request
访问GitHub并创建Pull Request。
提交规范¶
我们使用Conventional Commits规范：
Type类型:
feat: 新功能fix: Bug修复docs: 文档更新style: 代码格式（不影响代码运行）refactor: 重构test: 测试相关chore: 构建/工具相关
示例:
feat(styles): add gradient fill support
Add support for gradient fill in cell styles.
This includes linear and radial gradients.
Closes #123
代码规范¶
代码风格¶
- 使用Black格式化代码（88字符行宽）
- 使用isort排序导入
- 遵循PEP 8规范
- 使用有意义的变量名
类型注解¶
所有公开API必须有类型注解：
def set_cell_value(self, cell_ref: str, value: Any) -> None:
"""设置单元格值。
Args:
cell_ref: 单元格引用，如"A1"
value: 单元格值
"""
...
文档字符串¶
使用Google风格的文档字符串：
def create_worksheet(self, title: str = "Sheet") -> Worksheet:
"""创建新工作表。
Args:
title: 工作表名称。默认为"Sheet"。
Returns:
新创建的工作表对象。
Raises:
ValueError: 如果工作表名称已存在。
Example:
```python
sheet = wb.create_worksheet("数据")
```
"""
...
测试规范¶
编写测试¶
每个新功能都应该有对应的测试：
import pytest
from symphra_excel import Workbook
def test_create_worksheet():
"""测试创建工作表。"""
wb = Workbook()
sheet = wb.create_worksheet("测试")
assert sheet is not None
assert sheet.title == "测试"
assert "测试" in wb.worksheet_names
def test_create_duplicate_worksheet():
"""测试创建重名工作表应抛出异常。"""
wb = Workbook()
wb.create_worksheet("测试")
with pytest.raises(ValueError):
wb.create_worksheet("测试")
测试覆盖率¶
- 新代码的测试覆盖率应≥80%
- 关键路径应达到90%+覆盖率
- 使用
pytest --cov检查覆盖率
测试标记¶
使用pytest标记组织测试：
@pytest.mark.slow
def test_large_file():
"""测试大文件处理。"""
...
@pytest.mark.integration
def test_end_to_end():
"""端到端集成测试。"""
...
Pull Request规范¶
PR标题:
PR描述模板:
## 变更说明
[简要描述变更内容]
## 变更类型
- [ ] Bug修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 性能优化
- [ ] 重构
## 测试
- [ ] 添加了测试用例
- [ ] 所有测试通过
- [ ] 测试覆盖率≥80%
## 检查清单
- [ ] 代码通过Black格式化
- [ ] 代码通过isort排序
- [ ] 代码通过flake8检查
- [ ] 代码通过mypy类型检查
- [ ] 添加了文档字符串
- [ ] 更新了相关文档
## 关联Issue
Closes #123
## 截图/示例
[如果适用，添加截图或代码示例]
\```
## 文档贡献
### 文档结构
文档位于`docs/`目录：
### 编写文档
1. **使用Markdown格式**
2. **包含代码示例**
3. **添加适当的标题层级**
4. **使用清晰的语言**
### 预览文档
```bash
# 安装文档依赖
pip install -e ".[docs]"
# 本地预览
mkdocs serve
# 访问 http://127.0.0.1:8000
发布流程¶
（仅限维护者）
- 更新版本号
- 更新CHANGELOG
- 创建Git标签
- 构建分发包
- 上传到PyPI
行为准则¶
我们的承诺¶
我们致力于为每个人提供友好、安全和包容的环境。
我们的标准¶
正面行为:
- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心
不可接受的行为:
- 使用性化的语言或图像
- 侮辱/贬损性评论和人身攻击
- 公开或私下骚扰
- 未经许可发布他人私人信息
- 其他不道德或不专业的行为
执行¶
违反行为准则可能导致：
- 警告
- 临时禁止
- 永久禁止
获取帮助¶
如有任何问题：
致谢¶
感谢每一位贡献者！您的帮助让Symphra Excel变得更好。
查看所有贡献者：https://github.com/getaix/symphra-excel/graphs/contributors
再次感谢您的贡献！🎉