# 贡献指南

## 欢迎贡献

SPIRE 欢迎各种形式的贡献：

- Bug 修复
- 新功能
- 文档改进
- 测试增强
- 问题报告

## 贡献流程

### 1. 准备工作

```bash
# Fork 仓库到你的 GitHub 账户

# 克隆你的 Fork
git clone https://github.com/YOUR-USERNAME/spire.git
cd spire

# 添加上游仓库
git remote add upstream https://github.com/spiffe/spire.git
```

### 2. 创建分支

```bash
# 确保在最新的 main 分支
git checkout main
git pull upstream main

# 创建功能分支
git checkout -b feature/my-feature
```

### 3. 开发

```bash
# 编写代码...

# 运行测试
make test

# 代码检查
make lint
```

### 4. 提交

遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式：

```bash
# 格式: <type>(<scope>): <description>
git commit -m "feat(server): add new attestation method"
git commit -m "fix(agent): resolve memory leak in rotation"
git commit -m "docs: update configuration guide"
```

**Commit 类型：**

| 类型 | 描述 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档变更 |
| `style` | 代码格式（不影响运行） |
| `refactor` | 重构 |
| `test` | 测试相关 |
| `chore` | 构建或辅助工具变更 |

### 5. DCO 签名

所有提交必须包含 DCO (Developer Certificate of Origin) 签名：

```bash
git commit -s -m "feat: add new feature"
```

这会添加：

```
Signed-off-by: Your Name <your.email@example.com>
```

### 6. 推送和创建 PR

```bash
# 推送到你的 Fork
git push origin feature/my-feature

# 在 GitHub 上创建 Pull Request
```

## Pull Request 指南

### PR 标题

使用与 commit 相同的格式：

```
feat(server): add support for new attestor
```

### PR 描述

包含以下内容：

```markdown
## 描述
简要描述变更内容和原因。

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重大变更
- [ ] 文档更新

## 测试
描述如何测试这些变更。

## 相关 Issue
Fixes #123
```

### PR 检查清单

- [ ] 代码遵循项目规范
- [ ] 添加/更新了测试
- [ ] 所有测试通过
- [ ] 更新了相关文档
- [ ] DCO 签名正确

## 代码规范

### Go 代码风格

遵循 [Effective Go](https://golang.org/doc/effective_go) 和项目约定：

```go
// 正确的命名
type NodeAttestor interface {}
func AttestNode() {}

// 错误处理
if err != nil {
    return fmt.Errorf("failed to attest node: %w", err)
}

// 注释
// AttestNode performs node attestation using the configured attestor.
// It returns an error if attestation fails.
func AttestNode(ctx context.Context) error {
    // ...
}
```

### 代码检查

```bash
# 运行所有检查
make lint

# 手动运行 golangci-lint
golangci-lint run ./...
```

### 格式化

```bash
# 格式化代码
gofmt -w .

# 或使用 goimports
goimports -w .
```

## 文档贡献

### 文档位置

- `doc/`: 用户文档
- `man/`: 中文手册（本项目）
- 代码注释: API 文档

### 文档规范

- 使用清晰、简洁的语言
- 包含代码示例
- 保持格式一致

## Issue 报告

### Bug 报告

使用 Bug 报告模板：

```markdown
## Bug 描述
简要描述 bug。

## 重现步骤
1. 步骤 1
2. 步骤 2
3. ...

## 期望行为
描述期望发生什么。

## 实际行为
描述实际发生什么。

## 环境
- SPIRE 版本:
- 操作系统:
- Kubernetes 版本（如适用）:

## 日志
相关日志输出。
```

### 功能请求

```markdown
## 功能描述
描述你想要的功能。

## 使用场景
为什么需要这个功能？

## 建议实现
如何实现这个功能？
```

## 社区

### 沟通渠道

- **Slack**: [spiffe.slack.com](https://spiffe.slack.com/)
- **邮件列表**: [spiffe-dev](https://groups.google.com/g/spiffe-dev)
- **GitHub Discussions**: 项目讨论

### 行为准则

遵循 [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md)：

- 尊重他人
- 包容多样性
- 建设性沟通
- 关注项目利益

## 审查流程

### 审查标准

- 代码质量和可读性
- 测试覆盖
- 文档完整性
- 与现有代码的一致性
- 安全考虑

### 合并要求

- 至少一个维护者批准
- 所有 CI 检查通过
- 解决所有评论
- DCO 签名有效

## 发布流程

SPIRE 遵循语义化版本：

- **主版本**: 不兼容的 API 变更
- **次版本**: 向后兼容的新功能
- **补丁版本**: 向后兼容的 bug 修复

详见 [RELEASING.md](https://github.com/spiffe/spire/blob/main/RELEASING.md)。

## 获取帮助

如果需要帮助：

1. 查看现有文档和 Issue
2. 在 Slack #spire 频道提问
3. 创建 GitHub Discussion

:::{admonition} 感谢贡献！
:class: tip

每一份贡献都很重要，无论大小。感谢你帮助改进 SPIRE！
:::