Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
260 lines (186 loc) · 5.98 KB

CONTRIBUTING.md

File metadata and controls

260 lines (186 loc) · 5.98 KB
Raw

Contributing to GPL Radar

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

项目状态说明

当前状态: 个人维护项目

GPL Radar 目前是一个由个人（项目所有者）维护的开源项目。所有的开发、维护和发布工作目前均由项目所有者独立完成。虽然我们不拒绝外部贡献，但在提交贡献之前，请先阅读以下指南。

如何报告问题

如果您发现了 bug 或有功能建议，请通过 GitHub Issues 报告：

  1. 搜索现有 Issues: 在创建新 Issue 之前，请先搜索是否已存在相同或相似的问题
  2. 使用 Issue 模板: 选择合适的模板（Bug 报告或功能请求）
  3. 提供详细信息:
    • 对于 Bug: 复现步骤、期望行为、实际行为、系统环境
    • 对于功能请求: 使用场景、期望功能、可能的实现方案

报告安全漏洞

如果您发现了安全漏洞，请不要通过公开的 Issue 报告。请直接发送邮件至项目所有者：

📧 novelnexusai@outlook.com

开发环境搭建

前置要求

  • Python 3.9 或更高版本
  • Git
  • pip 包管理器

安装步骤

  1. Fork 仓库 (如果您计划提交 PR)

    # 点击 GitHub 页面上的 "Fork" 按钮

  2. 克隆仓库

    # 如果您是项目所有者
git clone https://github.com/PerryLink/gpl-radar.git

# 如果您是贡献者（已 Fork）
git clone https://github.com/YOUR_USERNAME/gpl-radar.git

  3. 安装依赖

    cd gpl-radar
pip install -e ".[dev]"

  4. 验证安装

    # 运行测试
pytest tests/

# 测试 CLI
scan-gpl --help

开发工作流

  1. 创建功能分支

    git checkout -b feature/your-feature-name
# 或
git checkout -b fix/bug-description

  2. 进行开发

    • 编写代码
    • 添加/更新测试
    • 确保所有测试通过

  3. 提交更改

    git add .
git commit -m "type: description"

  4. 推送到远程

    git push origin feature/your-feature-name

代码规范

Python 代码规范 (PEP 8)

本项目遵循 PEP 8 代码规范。主要要求如下：

缩进和空白

  • 使用 4 个空格缩进（不要使用 Tab）
  • 每行最大长度 88 个字符（Black 默认）
  • 函数和类之间用两个空行分隔
  • 方法之间用一个空行分隔

命名规范

  • 类名: 使用 PascalCase (如 RiskAnalyzer)
  • 函数和变量: 使用 snake_case (如 calculate_hash)
  • 常量: 使用 UPPER_SNAKE_CASE (如 MAX_K_GRAM_SIZE)
  • 私有成员: 以下划线开头 (如 _internal_method)

注释和文档字符串

  • 所有公共模块、类、方法必须有文档字符串
  • 使用 Google Style 或 NumPy Style 文档字符串
  • 复杂逻辑添加行内注释
def calculate_rolling_hash(tokens: list[str], k: int = 5) -> list[int]:
    """Calculate rolling hash for token sequence.
    
    Args:
        tokens: List of code tokens
        k: Window size for k-grams
        
    Returns:
        List of hash values for each window
        
    Example:
        >>> tokens = ['def', 'foo', '(', ')']
        >>> calculate_rolling_hash(tokens, k=2)
        [12345, 67890]
    """
    # Implementation here
    pass

代码格式化

使用 Black 进行代码格式化：

# 格式化整个项目
black src/ tests/

# 检查格式（不修改文件）
black --check src/ tests/

类型注解

项目使用 Python 类型注解，请为新代码添加类型提示：

from typing import List, Dict, Optional

def process_file(file_path: str, threshold: float = 0.8) -> Dict[str, int]:
    result: Dict[str, int] = {}
    # implementation
    return result

提交 Pull Request 的流程

准备 PR

  1. 确保代码质量

    # 运行测试
pytest tests/

# 检查代码格式
black --check src/ tests/

# 运行类型检查（如果有配置）
mypy src/

  2. 更新文档

    • 如果添加了新功能，更新 README.md
    • 如果修改了 API，更新相关文档

  3. 编写清晰的提交信息

提交 PR

  1. 创建 PR

    • 访问 GitHub 仓库页面
    • 点击 "New Pull Request"
    • 选择你的分支和要合并的目标分支

  2. 填写 PR 描述 使用以下模板：

    ## 描述
简要描述这个 PR 做了什么

## 更改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 性能优化
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他（请描述）

## 测试
- [ ] 添加了新测试
- [ ] 所有现有测试通过
- [ ] 手动测试了关键功能

## 检查清单
- [ ] 代码遵循项目代码规范
- [ ] 文档已更新（如需要）
- [ ] 提交信息清晰明确

## 相关问题
修复 #123

  3. 等待审核

    • 项目所有者会审核你的 PR
    • 可能需要根据反馈进行修改
    • 保持耐心，积极回应反馈

PR 审核流程

作为个人维护项目，PR 审核流程相对简单：

  1. 自动检查

    • CI/CD 运行测试（如果已配置）
    • 代码格式检查

  2. 人工审核

    • 项目所有者审核代码
    • 检查代码质量、功能正确性

  3. 合并

    • 审核通过后合并到主分支
    • 关闭相关 Issue（如果存在）

其他注意事项

沟通准则

  • 保持友好和尊重：所有交流都应专业和友善
  • 清晰明确：描述问题时提供足够的信息
  • 耐心：维护者是志愿者，回复可能需要时间

贡献认可

所有贡献者将在 README.md 的 Contributors 部分得到认可（当项目发展壮大时）。

许可证

通过贡献代码，您同意您的贡献将在 Apache License 2.0 下授权。

感谢您对 GPL Radar 的贡献！ 🎉