# CodeDetect 贡献指南

感谢您对CodeDetect项目的关注！本文档将指导您如何为项目做出贡献。

## 目录

- [行为准则](#行为准则)
- [开始贡献](#开始贡献)
- [开发环境设置](#开发环境设置)
- [代码规范](#代码规范)
- [测试规范](#测试规范)
- [提交规范](#提交规范)
- [Pull Request流程](#pull-request流程)
- [问题报告](#问题报告)
- [功能请求](#功能请求)

## 行为准则

### 我们的承诺

为了营造开放和友好的环境，我们作为贡献者和维护者承诺：

- 友善和包容
- 尊重不同观点和经验
- 耐心接受建设性批评
- 关注社区最大利益

### 不当行为

不当行为包括：

- 使用性暗示语言或图像
- 人身攻击或侮辱性评论
- 公开或私下骚扰
- 未经明确许可发布他人信息

## 开始贡献

### 寻找要贡献的内容

1. 查看 [Issues](https://github.com/your-username/codedetect/issues) 中标记为 "good first issue" 的问题
2. 查看 [Features](https://github.com/your-username/codedetect/issues) 中请求的功能
3. 改进文档
4. 修复拼写错误或格式问题
5. 添加测试用例

### 与团队沟通

- 在开始工作之前，先创建Issue讨论
- 在Issue中@相关维护者
- 加入我们的[社区讨论](https://github.com/your-username/codedetect/discussions)

## 开发环境设置

### 前提条件

- Python 3.8+
- Git
- CBMC (可选，用于运行完整测试)

### 克隆仓库

```bash
git clone https://github.com/your-username/codedetect.git
cd codedetect
```

### 设置开发环境

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt
pip install -r requirements-dev.txt

# 安装pre-commit hooks
pre-commit install
```

### 验证设置

```bash
# 运行测试
python -m pytest tests/unit/ -v

# 检查代码风格
black --check src/ tests/
flake8 src/ tests/
isort --check-only src/ tests/

# 检查类型
mypy src/
```

## 代码规范

### Python代码风格

我们遵循以下工具和规范：

- **Black**: 代码格式化
- **flake8**: 代码风格检查
- **isort**: 导入排序
- **mypy**: 类型检查

#### 格式化代码

```bash
# 格式化代码
black src/ tests/
isort src/ tests/

# 检查格式
black --check src/ tests/
isort --check-only src/ tests/
```

#### 代码风格规则

```python
# 好的示例
import os
from typing import List, Dict

class CodeProcessor:
    """代码处理器类"""

    def __init__(self, config: Dict[str, Any]):
        self.config = config

    def process_code(self, code: str) -> List[str]:
        """处理代码

        Args:
            code: 要处理的代码字符串

        Returns:
            处理后的代码行列表
        """
        if not code:
            return []

        return code.split('\n')

# 避免的做法
class codeProcessor:  # 类名应该使用CamelCase
    def __init__(self,config):  # 缺少空格和类型注解
        self.config=config
```

### 文档规范

#### 文档字符串

使用Google风格的文档字符串：

```python
def verify_function(
    function_name: str,
    source_code: str,
    options: Optional[Dict[str, Any]] = None
) -> VerificationResult:
    """验证函数的内存安全性。

    Args:
        function_name: 要验证的函数名
        source_code: 包含函数的源代码
        options: 可选的验证选项

    Returns:
        VerificationResult: 验证结果对象

    Raises:
        ValueError: 如果函数名或源代码无效
        VerificationError: 如果验证过程失败
    """
    pass
```

#### 注释规范

```python
# 好的注释
def process_data(data: List[str]) -> Dict[str, int]:
    """处理输入数据并返回统计信息。

    这个函数会去除空行，统计每个单词的出现频率，
    并返回频率最高的前10个单词。
    """
    # 过滤空行和空白字符
    filtered_data = [line.strip() for line in data if line.strip()]

    # 统计词频
    word_counts = {}
    for line in filtered_data:
        for word in line.split():
            word_counts[word] = word_counts.get(word, 0) + 1

    return word_counts

# 避免的注释
def bad_example(data):
    # 这个函数处理数据
    result = []  # 初始化结果列表
    for item in data:  # 遍历数据
        result.append(item)  # 添加到结果
    return result  # 返回结果
```

## 测试规范

### 测试结构

```
tests/
├── unit/           # 单元测试
├── integration/    # 集成测试
├── performance/    # 性能测试
├── regression/     # 回归测试
└── fixtures/       # 测试固件
```

### 编写测试

#### 单元测试示例

```python
import pytest
from unittest.mock import Mock, patch
from src.processor import CodeProcessor

class TestCodeProcessor:
    """代码处理器测试"""

    @pytest.fixture
    def processor(self):
        """创建处理器实例"""
        return CodeProcessor({"max_length": 100})

    def test_process_simple_code(self, processor):
        """测试简单代码处理"""
        code = "int main() { return 0; }"
        result = processor.process_code(code)

        assert len(result) == 1
        assert result[0] == "int main() { return 0; }"

    def test_process_empty_code(self, processor):
        """测试空代码处理"""
        result = processor.process_code("")
        assert result == []

    @patch('src.processor.external_api')
    def test_process_with_external_dependency(self, mock_api, processor):
        """测试有外部依赖的代码处理"""
        mock_api.return_value = {"status": "success"}

        result = processor.process_with_api("test code")

        mock_api.assert_called_once()
        assert result["status"] == "success"
```

#### 集成测试示例

```python
import pytest
from src.main import CodeDetectApp

class TestCodeDetectIntegration:
    """CodeDetect集成测试"""

    @pytest.fixture
    def app(self):
        """创建应用实例"""
        return CodeDetectApp()

    def test_full_verification_pipeline(self, app):
        """测试完整验证管道"""
        test_code = """
        int add(int a, int b) {
            return a + b;
        }
        """

        result = app.verify_code(test_code)

        assert result["success"] is True
        assert "verification_result" in result
        assert result["verification_result"]["status"] == "SUCCESS"
```

### 测试覆盖率要求

- **单元测试**: 最低80%行覆盖率
- **集成测试**: 覆盖所有主要功能路径
- **性能测试**: 覆盖关键性能指标
- **回归测试**: 覆盖所有已修复的问题

### 运行测试

```bash
# 运行所有测试
python -m pytest

# 运行特定测试类型
python -m pytest tests/unit/
python -m pytest tests/integration/

# 运行覆盖率测试
python -m pytest --cov=src/ --cov-report=html

# 运行性能测试
python -m pytest tests/performance/ -m "not slow"

# 并行运行测试
python -m pytest -n auto
```

## 提交规范

### 提交消息格式

```
<类型>(<范围>): <描述>

[可选的详细描述]

[可选的脚注]
```

### 提交类型

- **feat**: 新功能
- **fix**: 修复bug
- **docs**: 文档更新
- **style**: 代码格式化
- **refactor**: 代码重构
- **test**: 测试相关
- **chore**: 构建或工具变动

### 提交示例

```bash
# 好的提交
feat(verification): add support for array bounds checking
- Add array bounds checking functionality
- Update verification result format
- Add unit tests for new feature

fix(parser): fix null pointer dereference in code parsing
- Add null check before pointer access
- Fix issue #123
- Add regression test

docs(api): update API documentation
- Add new endpoint documentation
- Fix broken links
- Update examples

# 避免的提交
fix bug
update docs
minor changes
```

### 提交前检查

```bash
# 运行所有检查
./scripts/run-comprehensive-tests.sh

# 或者单独运行
python -m pytest
black --check src/ tests/
flake8 src/ tests/
mypy src/
```

## Pull Request流程

### PR流程

1. **Fork仓库**
2. **创建功能分支**
3. **编写代码和测试**
4. **确保所有测试通过**
5. **提交代码**
6. **创建Pull Request**
7. **响应审查意见**
8. **合并代码**

### 分支命名

```
feature/your-feature-name
fix/your-fix-name
docs/your-docs-update
```

### PR模板

```markdown
## 变更描述

简要描述这个PR的目的和变更内容。

## 变更类型

- [ ] Bug修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 重构
- [ ] 测试
- [ ] 其他: ___

## 相关Issue

Closes #123
Related to #456

## 测试

- [ ] 添加了单元测试
- [ ] 添加了集成测试
- [ ] 手动测试通过
- [ ] 所有现有测试通过

## 检查清单

- [ ] 代码遵循项目规范
- [ ] 文档已更新
- [ ] 测试覆盖率满足要求
- [ ] 无安全漏洞
- [ ] 性能影响已考虑
```

### PR审查指南

#### 审查者检查清单

- [ ] 代码是否清晰易懂
- [ ] 是否遵循项目规范
- [ ] 测试是否充分
- [ ] 文档是否更新
- [ ] 是否有潜在的安全问题
- [ ] 性能影响是否合理
- [ ] 错误处理是否完善

#### 审查评论示例

```markdown
### 代码审查

**总体印象**: 代码质量很好，逻辑清晰。

**建议**:
1. 在第45行，建议添加错误处理：
```python
try:
    result = dangerous_operation()
except Exception as e:
    logger.error(f"Operation failed: {e}")
    return None
```

2. 考虑将这个函数拆分成更小的函数以提高可读性

**问题**:
- 为什么选择使用这种算法而不是其他替代方案？

**表扬**:
- 测试覆盖很全面
- 错误处理很好
```

## 问题报告

### 报告Bug

使用GitHub Issue模板报告bug：

```markdown
## Bug描述

简要描述bug现象。

## 复现步骤

1. 执行操作A
2. 点击按钮B
3. 观察现象C

## 期望行为

描述期望的正确行为。

## 实际行为

描述实际观察到的行为。

## 环境信息

- 操作系统: Ubuntu 20.04
- Python版本: 3.9.0
- CodeDetect版本: v1.0.0
- CBMC版本: 5.10

## 其他信息

添加任何其他相关信息、截图、日志等。
```

### 功能请求

```markdown
## 功能描述

描述你希望添加的功能。

## 使用场景

描述这个功能的使用场景和用户需求。

## 建议实现

如果你有实现建议，请描述。

## 替代方案

描述你考虑过的替代方案。

## 附加信息

添加任何其他相关信息。
```

## 发布流程

### 版本号规范

- **主版本号**: 不兼容的API变更
- **次版本号**: 向后兼容的功能新增
- **修订号**: 向后兼容的问题修复

### 发布检查清单

- [ ] 所有测试通过
- [ ] 文档已更新
- [ ] 变更日志已更新
- [ ] 版本号已更新
- [ ] 安全检查通过
- [ ] 性能测试通过

## 获取帮助

如果您在贡献过程中遇到问题：

1. 查看 [文档](https://github.com/your-username/codedetect/docs)
2. 搜索现有的 [Issues](https://github.com/your-username/codedetect/issues)
3. 在 [Discussions](https://github.com/your-username/codedetect/discussions) 中提问
4. 联系维护者

## 致谢

感谢所有为CodeDetect项目做出贡献的开发者！

特别感谢：
- 所有Issue报告者
- 所有Pull Request贡献者
- 所有文档改进者
- 所有测试编写者

您的贡献使CodeDetect变得更好！🎉