Skip to content

为 Swit 做贡献

感谢您对为 Swit 微服务框架做贡献的兴趣!本指南将帮助您开始贡献代码、文档或报告问题。

目录

入门

在开始贡献之前,请:

  1. 阅读行为准则 - 所有贡献者都必须遵守我们的社区准则
  2. 检查现有问题 - 寻找您感兴趣的现有问题或功能请求
  3. 参与讨论 - 参与问题讨论以了解项目方向
  4. 从小开始 - 从小的错误修复或文档改进开始

贡献方式

代码贡献

  • 错误修复 - 修复报告的问题并提高稳定性
  • 新功能 - 实现新的框架功能或增强功能
  • 性能改进 - 优化现有代码以获得更好的性能
  • 示例服务 - 创建演示框架使用的新示例
  • 框架组件 - 添加新的传输层、中间件或实用程序

文档

  • API 文档 - 改进代码文档和 API 参考
  • 指南和教程 - 为框架功能编写综合指南
  • 示例文档 - 记录示例服务和用例
  • 翻译 - 帮助将文档翻译成其他语言

测试

  • 单元测试 - 为新功能编写测试或改进现有测试覆盖率
  • 集成测试 - 为框架组件创建端到端测试
  • 性能测试 - 开发基准测试和性能回归测试

社区支持

  • 问题分类 - 帮助分类和重现报告的问题
  • 代码审查 - 审查其他贡献者的拉取请求
  • 社区支持 - 帮助回答其他用户的问题

开发设置

前置条件

  • Go 1.24+ - 支持泛型的最新 Go 版本
  • Git - 版本控制系统
  • Make - 构建自动化工具
  • Docker(可选)- 用于构建容器镜像

环境设置

  1. Fork 并克隆仓库:

    bash
    # 首先在 GitHub 上 fork 仓库,然后克隆您的 fork
    git clone https://github.com/YOUR_USERNAME/swit.git
    cd swit
    
    # 添加上游远程仓库
    git remote add upstream https://github.com/innovationmech/swit.git
  2. 设置开发环境:

    bash
    # 安装开发工具和预提交钩子
    make setup-dev
  3. 验证设置:

    bash
    # 运行完整构建管道以确保一切正常
    make all

代码贡献流程

1. 查找或创建问题

  • 检查现有问题 - 寻找标记为 good first issuehelp wanted 的问题
  • 创建新问题 - 对于错误或功能请求,首先创建详细的问题
  • 讨论方法 - 对于重大更改,在问题中讨论您的方法

2. 创建功能分支

bash
# 确保您在主分支上且是最新的
git checkout master
git pull upstream master

# 创建新的功能分支
git checkout -b feature/your-feature-name
# 或用于错误修复
git checkout -b fix/issue-description

3. 进行更改

  • 编写清洁代码 - 遵循 Go 最佳实践和现有代码模式
  • 添加测试 - 为新功能包含单元测试
  • 更新文档 - 更新相关文档和示例
  • 彻底测试 - 运行完整测试套件并验证您的更改

4. 提交您的更改

bash
# 暂存您的更改
git add .

# 使用描述性消息提交(遵循常规提交格式)
git commit -m "feat(transport): add HTTP/2 support for HTTP transport

- 实现 HTTP/2 服务器配置选项  
- 为现有 HTTP 处理程序添加 HTTP/2 兼容性
- 使用 HTTP/2 示例更新文档
- 包括 HTTP/2 功能的单元测试

Closes #123"

5. 推送并创建拉取请求

bash
# 推送到您的 fork
git push origin feature/your-feature-name

# 通过 GitHub UI 创建拉取请求

代码标准

Go 代码风格

  • 遵循标准 Go 约定 - 使用 gofmtgoimportsgo vet
  • 编写自文档代码 - 使用清晰的变量名和函数签名
  • 添加代码注释 - 记录导出的函数和复杂逻辑
  • 正确处理错误 - 始终检查和适当处理错误
  • 使用结构化日志 - 在整个代码库中使用 zap 日志记录器

提交消息格式

使用常规提交格式以获得清晰的历史:

type(scope): description

[optional body]

[optional footer]

类型:

  • feat - 新功能
  • fix - 错误修复
  • docs - 文档更改
  • style - 代码样式更改(格式等)
  • refactor - 代码重构
  • test - 添加或修复测试
  • chore - 维护任务

示例:

feat(server): add graceful shutdown support
fix(transport): resolve gRPC connection leak
docs(guide): update installation instructions
test(pkg/server): add unit tests for server lifecycle

代码组织

  • 包结构 - 遵循现有的包组织模式
  • 接口 - 为可扩展性定义清晰的接口
  • 错误类型 - 为不同的失败模式创建自定义错误类型
  • 配置 - 使用带验证的结构化配置
  • 依赖注入 - 遵循已建立的 DI 模式

测试指南

单元测试

go
// 示例单元测试结构
func TestServiceRegistration(t *testing.T) {
    tests := []struct {
        name    string
        setup   func() (*Service, error)
        want    error
        wantErr bool
    }{
        {
            name: "成功注册",
            setup: func() (*Service, error) {
                return NewService("test"), nil
            },
            want:    nil,
            wantErr: false,
        },
        // 添加更多测试用例...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            service, err := tt.setup()
            require.NoError(t, err)
            
            // 测试功能
            err = service.Register()
            
            if tt.wantErr {
                assert.Error(t, err)
            } else {
                assert.NoError(t, err)
            }
        })
    }
}

集成测试

  • 使用测试容器 - 用于数据库和外部服务依赖
  • 测试真实场景 - 测试完整的请求/响应周期
  • 清理资源 - 始终正确清理测试资源
  • 测试超时 - 验证超时和取消行为

测试覆盖率

bash
# 生成覆盖率报告
make test-coverage

# 在浏览器中查看覆盖率
go tool cover -html=coverage.out

目标:

  • 80%+ 覆盖率 - 核心框架组件
  • 100% 覆盖率 - 关键路径代码
  • 有意义的测试 - 专注于行为,而不仅仅是行覆盖率

文档贡献

API 文档

  • Godoc 注释 - 记录所有导出的函数和类型
  • 示例 - 在文档中包含代码示例
  • 错误文档 - 记录可能的错误及其含义
go
// ProcessRequest 处理传入的服务请求,包括验证和错误处理。
// 它验证请求格式,处理业务逻辑,并返回正确格式的响应。
//
// 参数:
//   - ctx: 用于取消和超时的请求上下文
//   - req: 要处理的服务请求
//
// 返回:
//   - *Response: 处理后的响应数据
//   - error: 处理错误,包装了上下文信息
//
// 错误:
//   - ErrInvalidRequest: 当请求验证失败时
//   - ErrServiceUnavailable: 当所需依赖不可用时
//   - context.DeadlineExceeded: 当达到处理超时时
//
// 示例:
//   ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
//   defer cancel()
//   
//   response, err := service.ProcessRequest(ctx, &Request{Data: "example"})
//   if err != nil {
//       return fmt.Errorf("请求处理失败: %w", err)
//   }
func ProcessRequest(ctx context.Context, req *Request) (*Response, error) {
    // 实现...
}

指南文档

  • 清晰结构 - 使用一致的标题和组织
  • 可运行示例 - 提供完整、可运行的示例
  • 逐步说明 - 将复杂程序分解为清晰的步骤
  • 截图/图表 - 在有帮助的地方包含视觉辅助

文档标准

  • Markdown 格式 - 使用一致的 markdown 格式
  • 代码高亮 - 为代码块使用适当的语言标签
  • 链接 - 包含相关的交叉引用和外部链接
  • 版本兼容性 - 在相关的地方说明版本要求

问题报告

错误报告

报告错误时,请包含:

  1. 清晰描述 - 描述发生了什么与预期的情况
  2. 重现步骤 - 提供重现问题的最少步骤
  3. 环境详情 - Go 版本、操作系统、框架版本
  4. 代码示例 - 包含演示问题的最少代码
  5. 错误消息 - 包含完整的错误消息和堆栈跟踪

错误报告模板:

markdown
## 错误描述
错误的简要描述。

## 重现步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 预期行为
您期望发生的事情。

## 实际行为
实际发生的事情。

## 环境
- Go 版本:1.24.0
- 操作系统:Ubuntu 22.04
- 框架版本:v1.0.0

## 代码示例
```go
// 重现问题的最少代码

错误消息

完整的错误消息和堆栈跟踪

### 功能请求

对于功能请求,请包含:

1. **用例描述** - 解释您试图解决的问题
2. **建议解决方案** - 描述您的建议方法
3. **考虑的替代方案** - 提及您考虑过的其他方法
4. **实现想法** - 分享关于如何实现的想法

## 拉取请求流程

### 创建拉取请求之前

1. **与上游同步** - 确保您的分支与主分支保持最新
2. **运行完整测试套件** - 执行 `make ci` 运行所有质量检查
3. **更新文档** - 包含相关的文档更新
4. **编写有意义的测试** - 为新功能添加测试

### 拉取请求描述

在您的 PR 描述中包含:

- **摘要** - 更改的简要描述
- **相关问题** - 使用 `Closes #123` 引用相关问题
- **所做更改** - 列出主要更改
- **测试** - 描述您如何测试更改
- **破坏性更改** - 突出任何破坏性更改

**PR 模板:**
```markdown
## 摘要
此 PR 中更改的简要描述。

## 相关问题
Closes #123
Relates to #456

## 所做更改
- 为传输层添加了新的 HTTP/2 支持
- 更新了 HTTP/2 的配置选项
- 添加了 HTTP/2 功能的单元测试
- 使用 HTTP/2 示例更新了文档

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过  
- [ ] 手动测试完成
- [ ] 性能影响评估

## 破坏性更改
- [ ] 此 PR 包含破坏性更改
- [ ] 此 PR 向后兼容

## 检查清单
- [ ] 代码遵循项目风格指南
- [ ] 代码自审查完成
- [ ] 代码有注释,特别是在难以理解的区域
- [ ] 对文档进行了相应更改
- [ ] 添加了证明修复有效或功能工作的测试
- [ ] 新的和现有的单元测试在本地通过

审查流程

  1. 自动检查 - CI 管道必须通过
  2. 代码审查 - 需要至少一个维护者审查
  3. 处理反馈 - 及时回应审查意见
  4. 根据需要更新 - 进行请求的更改
  5. 最终批准 - 维护者批准合并

社区指南

沟通

  • 保持尊重 - 尊重所有社区成员
  • 建设性 - 提供有用的反馈和建议
  • 保持耐心 - 审查和响应可能需要时间
  • 提问 - 不要犹豫寻求帮助或澄清

协作

  • 分享知识 - 帮助其他贡献者学习和改进
  • 给予认可 - 承认他人的贡献
  • 包容 - 欢迎来自所有背景的贡献者
  • 跟进 - 回应反馈并继续对话

质量标准

  • 测试您的更改 - 确保您的代码在提交前工作
  • 记录您的工作 - 帮助他人理解您的贡献
  • 遵循约定 - 使用既定的模式和风格
  • 彻底审查 - 花时间审查您自己的更改

获得帮助

如果您在贡献时需要帮助:

  1. 检查现有文档 - 查看指南和示例
  2. 搜索问题 - 寻找类似的问题或问题
  3. 在讨论中提问 - 使用 GitHub 讨论进行一般问题
  4. 加入社区频道 - 参与社区论坛
  5. 标记维护者 - 对于紧急问题,尊重地标记维护者

认可

我们感谢对 Swit 项目的所有贡献!贡献者将:

  • 列入贡献者名单 - 在项目文档中得到认可
  • 在发布中获得认可 - 在发布说明中注明主要贡献
  • 受邀加入社区 - 访问贡献者讨论和活动

感谢您帮助让 Swit 对每个人都更好!🚀

Released under the MIT License.