# 贡献指南感谢您对 Sikuwa 项目的关注。本文档将指导您如何参与项目贡献。 --- ## 目录 - [行为准则](#行为准则) - [如何贡献](#如何贡献) - [开发环境](#开发环境) - [代码规范](#代码规范) - [提交规范](#提交规范) - [Pull Request 流程](#pull-request-流程) - [问题反馈](#问题反馈) --- ## 行为准则参与本项目时，请遵守以下原则： - 尊重所有贡献者 - 保持专业、友善的交流方式 - 接受建设性的批评和建议 - 专注于项目的最佳利益 --- ## 如何贡献 ### 贡献类型 | 类型 | 说明 | |:---|:---| | 报告 Bug | 通过 Issue 报告发现的问题 | | 功能建议 | 提出新功能或改进建议 | | 代码贡献 | 提交代码修复或新功能 | | 文档改进 | 完善项目文档 | | 测试用例 | 补充单元测试或集成测试 | ### 贡献流程 ``` 1. Fork 仓库 2. 创建分支 3. 编写代码 4. 运行测试 5. 提交更改 6. 创建 PR 7. 代码审查 8. 合并代码 ``` --- ## 开发环境 ### 环境要求 | 组件 | 版本 | |:---|:---| | Python | >= 3.7 | | pip | >= 21.0 | | Git | >= 2.0 | ### 环境搭建 **1. Fork 并克隆仓库** ```bash # GitHub git clone https://github.com//Sikuwa.git # Gitee git clone https://gitee.com//Sikuwa.git cd Sikuwa ``` **2. 创建虚拟环境** ```bash # Windows python -m venv .venv .venv\Scripts\activate # Linux/macOS python3 -m venv .venv source .venv/bin/activate ``` **3. 安装依赖** ```bash pip install click tomli tomli-w nuitka pytest ``` **4. 验证安装** ```bash python -m sikuwa --version pytest tests/ -v ``` ### 开发依赖 ``` click>=8.0 tomli>=2.0 (Python < 3.11) tomli-w>=1.0 nuitka>=2.0 pytest>=7.0 ``` --- ## 代码规范 ### Python 代码风格遵循 PEP 8 规范，并满足以下要求： **格式化** ```bash # 使用 black 格式化代码 black sikuwa/ # 使用 isort 排序导入 isort sikuwa/ ``` **类型注解** 所有公共函数和方法必须包含类型注解： ```python def build_project( config: BuildConfig, platform: Optional[str] = None, verbose: bool = False ) -> bool: """构建项目""" ... ``` **文档字符串** 使用 Google 风格的 docstring： ```python def compile_module(source: Path, output: Path) -> CompileResult: """编译单个模块。 Args: source: 源文件路径 output: 输出文件路径 Returns: CompileResult: 编译结果对象 Raises: CompileError: 编译失败时抛出 """ ... ``` ### 命名规范 | 类型 | 规范 | 示例 | |:---|:---|:---| | 模块 | 小写下划线 | `smart_cache.py` | | 类 | 大驼峰 | `SikuwaBuilder` | | 函数/方法 | 小写下划线 | `build_project` | | 常量 | 大写下划线 | `MAX_RETRY_COUNT` | | 私有成员 | 单下划线前缀 | `_internal_method` | ### 代码检查提交前运行代码检查： ```bash # 类型检查 mypy sikuwa/ # 代码风格检查 black --check sikuwa/ isort --check sikuwa/ # 运行测试 pytest tests/ -v --cov=sikuwa ``` --- ## 提交规范 ### 提交信息格式 ``` ():