为 Swit 做贡献
感谢您对为 Swit 微服务框架做贡献的兴趣!本指南将帮助您开始贡献代码、文档或报告问题。
目录
入门
在开始贡献之前,请:
- 阅读行为准则 - 所有贡献者都必须遵守我们的社区准则
- 检查现有问题 - 寻找您感兴趣的现有问题或功能请求
- 参与讨论 - 参与问题讨论以了解项目方向
- 从小开始 - 从小的错误修复或文档改进开始
贡献方式
代码贡献
- 错误修复 - 修复报告的问题并提高稳定性
- 新功能 - 实现新的框架功能或增强功能
- 性能改进 - 优化现有代码以获得更好的性能
- 示例服务 - 创建演示框架使用的新示例
- 框架组件 - 添加新的传输层、中间件或实用程序
文档
- API 文档 - 改进代码文档和 API 参考
- 指南和教程 - 为框架功能编写综合指南
- 示例文档 - 记录示例服务和用例
- 翻译 - 帮助将文档翻译成其他语言
测试
- 单元测试 - 为新功能编写测试或改进现有测试覆盖率
- 集成测试 - 为框架组件创建端到端测试
- 性能测试 - 开发基准测试和性能回归测试
社区支持
- 问题分类 - 帮助分类和重现报告的问题
- 代码审查 - 审查其他贡献者的拉取请求
- 社区支持 - 帮助回答其他用户的问题
开发设置
前置条件
- Go 1.24+ - 支持泛型的最新 Go 版本
- Git - 版本控制系统
- Make - 构建自动化工具
- Docker(可选)- 用于构建容器镜像
环境设置
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
设置开发环境:
bash# 安装开发工具和预提交钩子 make setup-dev
验证设置:
bash# 运行完整构建管道以确保一切正常 make all
代码贡献流程
1. 查找或创建问题
- 检查现有问题 - 寻找标记为
good first issue
或help 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 约定 - 使用
gofmt
、goimports
和go 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 格式
- 代码高亮 - 为代码块使用适当的语言标签
- 链接 - 包含相关的交叉引用和外部链接
- 版本兼容性 - 在相关的地方说明版本要求
问题报告
错误报告
报告错误时,请包含:
- 清晰描述 - 描述发生了什么与预期的情况
- 重现步骤 - 提供重现问题的最少步骤
- 环境详情 - Go 版本、操作系统、框架版本
- 代码示例 - 包含演示问题的最少代码
- 错误消息 - 包含完整的错误消息和堆栈跟踪
错误报告模板:
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 向后兼容
## 检查清单
- [ ] 代码遵循项目风格指南
- [ ] 代码自审查完成
- [ ] 代码有注释,特别是在难以理解的区域
- [ ] 对文档进行了相应更改
- [ ] 添加了证明修复有效或功能工作的测试
- [ ] 新的和现有的单元测试在本地通过
审查流程
- 自动检查 - CI 管道必须通过
- 代码审查 - 需要至少一个维护者审查
- 处理反馈 - 及时回应审查意见
- 根据需要更新 - 进行请求的更改
- 最终批准 - 维护者批准合并
社区指南
沟通
- 保持尊重 - 尊重所有社区成员
- 建设性 - 提供有用的反馈和建议
- 保持耐心 - 审查和响应可能需要时间
- 提问 - 不要犹豫寻求帮助或澄清
协作
- 分享知识 - 帮助其他贡献者学习和改进
- 给予认可 - 承认他人的贡献
- 包容 - 欢迎来自所有背景的贡献者
- 跟进 - 回应反馈并继续对话
质量标准
- 测试您的更改 - 确保您的代码在提交前工作
- 记录您的工作 - 帮助他人理解您的贡献
- 遵循约定 - 使用既定的模式和风格
- 彻底审查 - 花时间审查您自己的更改
获得帮助
如果您在贡献时需要帮助:
- 检查现有文档 - 查看指南和示例
- 搜索问题 - 寻找类似的问题或问题
- 在讨论中提问 - 使用 GitHub 讨论进行一般问题
- 加入社区频道 - 参与社区论坛
- 标记维护者 - 对于紧急问题,尊重地标记维护者
认可
我们感谢对 Swit 项目的所有贡献!贡献者将:
- 列入贡献者名单 - 在项目文档中得到认可
- 在发布中获得认可 - 在发布说明中注明主要贡献
- 受邀加入社区 - 访问贡献者讨论和活动
感谢您帮助让 Swit 对每个人都更好!🚀