# 贡献指南 感谢您考虑为国家经济数据分析平台 (NEDAP) 做出贡献！ ## 📋 目录 - [行为准则](#行为准则) - [如何贡献](#如何贡献) - [开发环境设置](#开发环境设置) - [代码规范](#代码规范) - [提交规范](#提交规范) - [Pull Request 流程](#pull-request-流程) - [问题报告](#问题报告) - [功能请求](#功能请求) --- ## 行为准则 本项目采用贡献者公约作为行为准则。参与本项目即表示您同意遵守其条款。请阅读 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 了解详情。 ### 我们的承诺 - 使用包容、友好的语言 - 尊重不同的观点和经验 - 优雅地接受建设性批评 - 关注对社区最有利的事情 - 对其他社区成员表示同理心 --- ## 如何贡献 ### 报告 Bug 如果您发现了 Bug，请创建一个 [Issue](https://github.com/badhope/national_stats/issues)，包含： 1. **清晰的标题**：简明扼要地描述问题 2. **复现步骤**：详细的步骤让他人能复现问题 3. **预期行为**：您期望发生什么 4. **实际行为**：实际发生了什么 5. **环境信息**： - 操作系统和版本 - Python 版本 - 项目版本 6. **截图**：如果适用，添加截图帮助解释问题 7. **日志**：相关的错误日志或堆栈跟踪 ### 功能请求 如果您有功能建议，请创建一个 [Issue](https://github.com/badhope/national_stats/issues)，包含： 1. **清晰的标题**：简明扼要地描述功能 2. **详细描述**：功能的详细说明 3. **用例**：为什么需要这个功能 4. **替代方案**：您考虑过的替代方案 5. **优先级**：对您来说这个功能有多重要 ### 提交代码 1. Fork 本仓库 2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`) 3. 进行更改 4. 确保通过所有测试 (`pytest tests/`) 5. 确保代码符合规范 (`black .` 和 `flake8 .`) 6. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`) 7. 推送到分支 (`git push origin feature/AmazingFeature`) 8. 创建 Pull Request --- ## 开发环境设置 ### 1. 克隆仓库 ```bash git clone https://github.com/badhope/national_stats.git cd national_stats ``` ### 2. 创建虚拟环境 ```bash # 使用 venv python -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate ``` ### 3. 安装依赖 ```bash pip install -r requirements.txt pip install -r requirements-dev.txt ``` ### 4. 安装预提交钩子 ```bash pre-commit install ``` --- ## 代码规范 ### Python 代码风格 我们使用以下工具确保代码质量： - **Black**：代码格式化 - **Flake8**：代码检查 - **isort**：导入排序 - **mypy**：类型检查 ### 格式化代码 ```bash # 格式化所有 Python 文件 black . # 排序导入 isort . # 检查代码质量 flake8 . # 类型检查 mypy backend/ ``` ### 代码风格指南 #### 命名约定 - **变量和函数**：使用 snake_case ```python def calculate_deficit_rate(revenue, expenditure): deficit = expenditure - revenue return deficit ``` - **类**：使用 PascalCase ```python class EconomicModel: pass ``` - **常量**：使用全大写 SNAKE_CASE ```python MAX_RETRIES = 3 DEFAULT_TIMEOUT = 30 ``` #### 文档字符串 使用 Google 风格的文档字符串： ```python def calculate_indicator(data: pd.DataFrame, method: str = "linear") -> Dict[str, float]: """计算经济指标。 Args: data: 包含经济数据的 DataFrame。 method: 计算方法，可选 "linear" 或 "monte_carlo"。 Returns: 包含计算结果的字典，键为指标名，值为计算结果。 Raises: ValueError: 如果数据为空或方法无效。 Example: >>> df = pd.DataFrame({"gdp": [100, 200, 300]}) >>> result = calculate_indicator(df, "linear") """ pass ``` #### 类型注解 所有公共函数都应使用类型注解： ```python from typing import List, Dict, Optional def process_data( indicators: List[str], config: Optional[Dict[str, Any]] = None ) -> pd.DataFrame: pass ``` --- ## 提交规范 我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： ### 提交消息格式 ``` ():