# 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) 发布。