Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (149 loc) · 4.24 KB

CONTRIBUTING.md

File metadata and controls

199 lines (149 loc) · 4.24 KB
Raw

datax 贡献指南

感谢你对 datax 项目的兴趣！本指南将帮助你参与项目开发。

开发环境设置

前提条件

  • Python 3.8+
  • pip 和 virtualenv（推荐）

快速开始

# 克隆项目
git clone https://github.com/yourusername/datax.git
cd datax

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"
pip install pytest flake8 black

代码风格

我们遵循 PEP 8 规范，使用 black 进行自动格式化：

make format        # 自动格式化代码
make lint          # 检查代码风格

测试

每个新功能或修复都必须包含测试：

make test          # 运行所有测试
python -m pytest datax/tests/test_datax.py::TestIntentMatcher -v  # 运行特定测试

提交流程

  1. 创建 Feature 分支

    git checkout -b feature/你的功能名

  2. 开发与测试

    • 编写代码
    • 运行 make test 确保通过测试
    • 运行 make lint 检查代码风格
    • 运行 make format 格式化代码

  3. 提交 Commit

    git add .
git commit -m "feat: 添加新功能描述"

  4. 推送与创建 PR

    git push origin feature/你的功能名

Commit 信息规范

使用 Conventional Commits 格式：

  • feat: 新功能
  • fix: 错误修复
  • docs: 文档更新
  • test: 测试新增或修改
  • refactor: 代码重构
  • perf: 性能优化
  • chore: 其他更改

示例：

feat: 支持 --stream 流式处理
fix: 修复 IP 提取正则表达式
docs: 更新 README 安装说明

项目结构

datax/
├── datax/
│   ├── __init__.py
│   ├── cli.py              # 命令行入口
│   ├── intent.py           # 意图识别和模板匹配
│   ├── llm.py              # LLM 接口（OpenAI、Ollama等）
│   ├── output.py           # 输出格式化
│   ├── config.py           # 配置管理
│   ├── templates/          # 本地模板库
│   └── tests/              # 单元测试
├── setup.py                # 安装配置
├── requirements.txt        # 依赖列表
└── README.md              # 项目说明

如何贡献

1. 添加新的本地模板

在 datax/intent.py 中注册新模板：

def _register_default_templates(self):
    # ... 现有模板 ...
    
    # 添加新模板
    self.register_template(
        "my_template",
        ["关键词1", "关键词2"],
        self._handler_my_template
    )

@staticmethod
def _handler_my_template(data: str, **kwargs) -> str:
    """处理数据的函数"""
    result = []
    for line in data.split('\n'):
        # 你的处理逻辑
        result.append(line)
    return '\n'.join(result)

然后在 datax/tests/test_datax.py 中添加测试。

2. 支持新的 LLM 提供商

在 datax/llm.py 中继承 LLMProvider：

class MyLLMProvider(LLMProvider):
    def __init__(self, ...):
        # 初始化
        pass
    
    def call(self, prompt: str, stream: bool = False) -> str:
        # 实现 API 调用
        pass
    
    def stream_call(self, prompt: str) -> Iterator[str]:
        # 实现流式调用
        pass

3. 改进输出格式

在 datax/output.py 中添加新格式处理：

@staticmethod
def _to_yaml(data: str) -> str:
    """Convert to YAML format"""
    # 实现转换逻辑
    pass

4. 文档和示例

  • 改进 README.md 和 DEMO.md
  • 添加使用示例
  • 提交翻译（中文/英文）

已知问题和改进空间

  • 支持流式处理大文件
  • 添加更多本地模板（JSON、CSV、SQL 等）
  • 支持管道链式处理（datax "..." | datax "..."）
  • Web UI 或 VS Code 插件
  • 性能优化和缓存机制
  • 完整的错误恢复和日志

报告问题

在 GitHub Issues 中报告问题时，请提供：

  • 清晰的问题描述
  • 复现步骤
  • 预期行为 vs 实际行为
  • 环境信息（Python 版本、操作系统等）
  • 相关的错误日志或输出

联系方式

  • Issues：提交 bug 或功能建议
  • Discussions：讨论设计和架构
  • Pull Requests：贡献代码

感谢你的贡献！🚀