# 贡献指南

感谢你有兴趣为《Claude Code for Spatial Intelligence and Autonomous Design》做出贡献！

---

## 如何贡献

### 报告问题

如果你发现了书中的错误或有改进建议：

1. 在GitHub Issues中搜索是否已有相关问题
2. 如果没有，创建新Issue并包含：
   - 清晰的标题
   - 错误位置（章节、文件）
   - 问题描述
   - 建议的改进方式
   - 相关标签（bug, enhancement, content等）

### 提交内容

#### 内容贡献类型

1. **修正错误**
   - 事实错误
   - 代码错误
   - 排版问题

2. **新增内容**
   - 新的示例代码
   - 新的案例分析
   - 新的实践项目

3. **改进现有内容**
   - 更好的解释
   - 更清晰的代码
   - 更好的组织

4. **翻译**
   - 英文内容的中译
   - 中文内容的英译

#### 提交流程

```bash
# 1. Fork仓库
# 点击GitHub上的Fork按钮

# 2. 克隆你的fork
git clone https://github.com/your-username/CC4SI.git
cd CC4SI

# 3. 创建分支
git checkout -b feature/your-feature-name

# 4. 做出修改
# 编辑文件...

# 5. 提交修改
git add .
git commit -m "描述你的修改"

# 6. 推送到你的fork
git push origin feature/your-feature-name

# 7. 创建Pull Request
# 在GitHub上创建PR
```

#### 提交信息规范

```
<type>(<scope>): <subject>

<body>

<footer>
```

**类型（type）**：
- `fix`: 修复bug
- `feat`: 新功能
- `docs`: 文档修改
- `style`: 格式修改
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具相关

**示例**：
```
fix(01-foundations): 修正状态机示例中的变量名错误

- 将 `state_machine` 改为 `workflow_state`
- 更新相关注释

Closes #123
```

---

## 内容规范

### Markdown格式

```markdown
# 一级标题（章节标题）

## 二级标题（小节标题）

### 三级标题（子小节）

#### 四级标题（通常不需要）

**粗体**用于强调
*斜体*用于术语
`代码`使用反引号
```

### 代码规范

Python代码示例应遵循：

1. **PEP 8**风格指南
2. **类型提示**：函数签名包含类型
3. **文档字符串**：重要函数有docstring
4. **注释**：关键逻辑有解释

```python
from typing import List, Dict, Optional

def analyze_ecological_network(
    sources: List[Dict],
    resistance_surface: np.ndarray,
    threshold: float = 0.5
) -> Dict:
    """
    分析生态网络

    Args:
        sources: 源地列表
        resistance_surface: 阻力面
        threshold: 连接阈值

    Returns:
        分析结果字典
    """
    # 实现逻辑...
    pass
```

### 示例代码要求

1. **可运行**：示例代码应该能直接运行
2. **自包含**：包含必要的import
3. **有输出**：展示预期输出
4. **有注释**：解释关键步骤

### 图表和可视化

优先使用代码生成图表：

```python
import matplotlib.pyplot as plt

# 创建图表
fig, ax = plt.subplots(figsize=(10, 6))
ax.plot([1, 2, 3], [1, 4, 9])
ax.set_title("示例图表")
ax.set_xlabel("X轴")
ax.set_ylabel("Y轴")

# 保存（如果需要）
# plt.savefig('output.png', dpi=300)

plt.show()
```

---

## 写作指南

### 章节模板

每章遵循以下结构：

```markdown
# 章节标题

## 核心问题
> 用1-2个引人思考的问题开场

## 概念讲解
（原理阐述，配合示例）

## 设计原理
（为什么这样设计，权衡是什么）

## 代码示例
```python
# 可运行代码
```

## 案例分析
（真实项目解析）

## 反思与延伸
### 思考问题
### 延伸阅读

## 关键要点
（总结本章核心）
```

### 语言风格

1. **清晰直接**：避免冗长的句子
2. **专业准确**：术语使用正确
3. **读者友好**：从读者角度写作
4. **主动语态**：多用主动语态

---

## 实践项目规范

### 项目结构

```
projects/project-name/
├── README.md           # 项目说明
├── requirements.txt    # 依赖
├── data/              # 示例数据
├── src/               # 源代码
│   └── __init__.py
├── notebooks/         # Jupyter notebooks（可选）
├── tests/             # 测试
│   └── __init__.py
└── outputs/           # 预期输出
```

### README规范

```markdown
# 项目名称

## 目标
（项目要达成的目标）

## 涉及技术
（列表说明使用的技术和方法）

## 实现步骤
1. 步骤一
2. 步骤二
...

## 运行方法
```bash
# 命令示例
```

## 预期输出
（展示预期结果）

## 扩展方向
（可选的改进方向）
```

---

## 审查流程

### Pull Request检查清单

提交PR前确认：

- [ ] 代码符合风格规范
- [ ] 包含必要的文档
- [ ] 示例代码可运行
- [ ] 没有新的警告
- [ ] 更新了相关文档

### 审查标准

PR将被评估：

1. **准确性**：内容是否正确
2. **清晰性**：是否易于理解
3. **完整性**：是否有遗漏
4. **一致性**：与现有内容风格一致
5. **价值**：是否为读者增加价值

---

## 许可

贡献的内容将遵循项目的许可证：CC BY-NC-SA 4.0

贡献即表示你同意：
- 你的贡献将按照此许可证发布
- 你拥有贡献内容的权利
- 你的贡献是自愿的，无报酬的

---

## 社区

### 行为准则

1. **尊重**：尊重所有贡献者
2. **包容**：欢迎不同背景的贡献者
3. **建设性**：提供建设性反馈
4. **协作**：以合作精神工作

### 沟通渠道

- **GitHub Issues**: 报告问题和讨论
- **Pull Requests**: 代码和内容贡献
- **Discussions**: 一般性讨论

---

## 致谢

所有贡献者将被列在项目首页的[Contributors](CONTRIBUTORS.md)中。

感谢你让这本书变得更好！
