197 lines
3.9 KiB
Markdown
197 lines
3.9 KiB
Markdown
# DevPack 贡献指南
|
||
|
||
> 感谢你对 DevPack 的兴趣！我们欢迎各种形式的贡献。
|
||
|
||
---
|
||
|
||
## 如何贡献
|
||
|
||
### 🐛 报告 Bug
|
||
|
||
1. 搜索 [已有的 Issues](https://github.com/user/devpack/issues)，确认没有重复
|
||
2. 创建新 Issue，包含以下信息：
|
||
- DevPack 版本（`devpack version`）
|
||
- 操作系统和版本
|
||
- 复现步骤
|
||
- 期望行为 vs 实际行为
|
||
- 日志信息（`--log-level debug`）
|
||
|
||
### 💡 功能建议
|
||
|
||
1. 搜索已有 Issues，确认没有类似建议
|
||
2. 创建 Feature Request Issue
|
||
3. 描述使用场景和期望行为
|
||
4. 解释为什么这个功能对用户有价值
|
||
|
||
### 🔧 提交代码
|
||
|
||
#### 环境准备
|
||
|
||
```bash
|
||
# 1. Fork 项目
|
||
|
||
# 2. Clone 你的 Fork
|
||
git clone https://github.com/YOUR_USERNAME/devpack.git
|
||
cd devpack
|
||
|
||
# 3. 添加上游仓库
|
||
git remote add upstream https://github.com/user/devpack.git
|
||
|
||
# 4. 安装依赖
|
||
go mod download
|
||
|
||
# 5. 安装开发工具
|
||
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
||
|
||
# 6. 验证环境
|
||
make test
|
||
make lint
|
||
```
|
||
|
||
#### 开发流程
|
||
|
||
```bash
|
||
# 1. 同步上游
|
||
git fetch upstream
|
||
git checkout develop
|
||
git merge upstream/develop
|
||
|
||
# 2. 创建分支
|
||
git checkout -b feature/your-feature
|
||
|
||
# 3. 编码
|
||
# ... 编写代码和测试
|
||
|
||
# 4. 运行检查
|
||
make fmt # 格式化代码
|
||
make lint # 代码检查
|
||
make test # 运行测试
|
||
|
||
# 5. 提交
|
||
git add .
|
||
git commit -m "feat(scope): description"
|
||
|
||
# 6. 推送
|
||
git push origin feature/your-feature
|
||
|
||
# 7. 创建 Pull Request
|
||
```
|
||
|
||
#### Pull Request 规范
|
||
|
||
- **标题：** 遵循 Conventional Commits 格式
|
||
- **描述：** 说明改了什么、为什么改、怎么测试的
|
||
- **关联 Issue：** 如果有对应的 Issue，请关联
|
||
- **测试：** 确保新代码有对应的测试
|
||
- **文档：** 如果改变了用户可见行为，更新对应文档
|
||
|
||
#### PR 模板
|
||
|
||
```markdown
|
||
## 描述
|
||
|
||
简述这个 PR 做了什么。
|
||
|
||
## 改动类型
|
||
|
||
- [ ] Bug fix
|
||
- [ ] New feature
|
||
- [ ] Refactoring
|
||
- [ ] Documentation
|
||
- [ ] Test
|
||
|
||
## 关联 Issue
|
||
|
||
Fixes #123
|
||
|
||
## 测试
|
||
|
||
描述如何测试这个改动。
|
||
|
||
## 检查清单
|
||
|
||
- [ ] 代码通过 `make lint`
|
||
- [ ] 添加了对应的单元测试
|
||
- [ ] 所有测试通过 `make test`
|
||
- [ ] 更新了相关文档
|
||
```
|
||
|
||
---
|
||
|
||
## 编码规范
|
||
|
||
### Go 代码规范
|
||
|
||
- 遵循 [Effective Go](https://golang.org/doc/effective_go)
|
||
- 使用 `gofmt` 格式化代码
|
||
- 通过 `golangci-lint` 检查
|
||
- 公开 API 必须有文档注释
|
||
- 错误必须包含上下文信息
|
||
|
||
### 提交规范
|
||
|
||
使用 [Conventional Commits](https://www.conventionalcommits.org/)：
|
||
|
||
```
|
||
feat(collector): add Docker runtime collector
|
||
fix(restore): handle version conflict correctly
|
||
docs(readme): update installation instructions
|
||
test(pack): add pack/unpack round-trip test
|
||
refactor(platform): simplify Windows adapter
|
||
chore(ci): add macOS build matrix
|
||
```
|
||
|
||
### 测试规范
|
||
|
||
- 所有新功能必须有单元测试
|
||
- 测试文件与源码在同一包下
|
||
- 使用 `testify` 断言库
|
||
- 平台特定逻辑需要条件跳过：
|
||
|
||
```go
|
||
func TestWindowsSpecific(t *testing.T) {
|
||
if runtime.GOOS != "windows" {
|
||
t.Skip("Windows-only test")
|
||
}
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 添加新采集器
|
||
|
||
如果你想为 DevPack 添加一个新的采集器，请参考以下步骤：
|
||
|
||
1. 在 `internal/collector/` 下创建新的包
|
||
2. 实现 `Collector` 接口的所有方法
|
||
3. 在 `registry.go` 中注册
|
||
4. 编写单元测试
|
||
5. 更新文档（PRD.md 和 USER-GUIDE.md）
|
||
|
||
详细指南请参考 [开发指南 - 添加新采集器](DEVELOPMENT.md#5-添加新采集器指南)。
|
||
|
||
---
|
||
|
||
## 社区准则
|
||
|
||
- 友善和尊重
|
||
- 建设性的讨论
|
||
- 接受不同意见
|
||
- 关注事实和技术
|
||
|
||
---
|
||
|
||
## 获取帮助
|
||
|
||
- 📖 [用户手册](USER-GUIDE.md)
|
||
- 🏗️ [架构设计](ARCHITECTURE.md)
|
||
- 💻 [开发指南](DEVELOPMENT.md)
|
||
- ❓ [GitHub Discussions](https://github.com/user/devpack/discussions)
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
贡献的代码将按照项目的 [MIT License](../LICENSE) 发布。
|