贡献指南

感谢你对 SuperSQL 的兴趣！我们欢迎任何形式的贡献。

如何贡献

报告 Bug

如果你发现了 Bug，请：

1. 在 GitHub Issues 上提交 Issue
2. 提供详细的 Bug 描述和复现步骤
3. 如果可能，提供修复建议

提出新功能

如果你有新功能的想法：

1. 在 GitHub Discussions 中讨论
2. 描述功能的用例和实现方式
3. 考虑实现难度和影响范围

提交代码

如果你想提交代码：

1. Fork 项目仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 进行开发并提交更改
4. 推送到你的 Fork：git push origin feature/your-feature-name
5. 创建 Pull Request

改进文档

如果你发现文档问题或想改进文档：

1. 在 docs 目录中修改或添加文档
2. 确保文档格式正确
3. 提交文档更改

开发环境

环境要求

• Java: JDK 21 或更高版本
• Maven: 3.6+ 或 Gradle 7+
• IDE: IntelliJ IDEA、Eclipse 或 VS Code

构建项目

mvn clean install

运行测试

mvn test

代码规范

Java 代码规范

• 使用 4 空格缩进
• 类名使用大驼峰命名
• 方法名和变量名使用小驼峰命名
• 常量名使用全大写下划线命名
• 添加适当的注释

Git 提交规范

提交信息格式：

<type>(<scope>): <subject>

<type> 可以是：
- feat: 新功能
- fix: 修复 Bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建/工具链相关

示例：
feat(core): 添加新的 RAG 检索功能
fix(api): 修复 SQL 生成错误
docs: 更新 API 文档

Pull Request 指南

PR 标题

使用清晰的标题描述你的更改：

[Feature] 添加对 PostgreSQL 的支持

或

[Fix] 修复连接超时问题

PR 描述

在 PR 描述中包含：

1. 更改的目的和背景
2. 实现的详细说明
3. 相关的 Issue 链接
4. 测试说明
5. 截图或演示（如果适用）

代码审查

• 确保代码通过所有检查
• 添加必要的单元测试
• 更新相关文档
• 遵循项目的代码风格

测试

单元测试

为你的代码编写单元测试：

@SpringBootTest
class SuperSqlEngineTest {

    @Autowired
    private SpringSqlEngine sqlEngine;

    @Test
    void testGenerateSql() {
        String sql = sqlEngine.generateSql("查询所有用户");
        assertNotNull(sql);
        assertTrue(sql.contains("SELECT"));
    }
}

集成测试

确保你的更改不会破坏现有功能：

mvn clean test

发布流程

版本号

遵循语义化版本号：MAJOR.MINOR.PATCH

• MAJOR: 不兼容的 API 变更
• MINOR: 向后兼容的功能性新增
• PATCH: 向后兼容的问题修复

发布检查清单

• 更新版本号
• 更新 CHANGELOG
• 运行所有测试
• 构建文档
• 创建 Git tag
• 推送到 Maven Central

获取帮助

如果你在贡献过程中遇到任何问题：

1. 查看 常见问题
2. 在 GitHub Discussions 中提问
3. 联系维护者

致谢

再次感谢你的贡献！每一个贡献都让 SuperSQL 变得更好。