gaokao-volunteer-system/CONTRIBUTING.md

贡献指南

感谢您对高考志愿填报项目的关注！我们欢迎任何形式的贡献。

---

🤝 如何贡献

1. 发现新问题

• 在真实咨询中发现新的错误模式
• 提出流程优化建议
• 报告Bug

2. 改进现有功能

• 修复已知Bug
• 优化算法
• 完善文档

3. 添加新功能

• 增加省份支持
• 添加新检查规则
• 开发新工具

4. 分享经验

• 记录真实案例
• 总结优化经验
• 编写教程

---

📋 贡献流程

步骤1：Fork项目（或本地分支）

# 创建分支
git checkout -b feature/你的功能名称

# 或
git checkout -b fix/bug描述

步骤2：进行修改

如果是修复错误模式

# 1. 编辑错误模式库
nano rules/errors/ERRORS.md

# 2. 添加测试用例
cp tests/cases/template.md tests/cases/你的测试.md

# 3. 更新规则文件
# 修改 skills/gaokao-spec-checker/scripts/spec_checker_v2.py

# 4. 添加测试
# 修改 tests/test_all.py

如果是优化Skill

# 1. 编辑Skill文件
nano skills/gaokao-college-advisor/SKILL.md

# 2. 更新案例
cp skills/gaokao-college-advisor/cases/TEMPLATE.md \
   skills/gaokao-college-advisor/cases/新案例.md

# 3. 运行测试
python3 tests/test_all.py

步骤3：提交更改

# 查看修改
git status

# 添加文件
git add .

# 提交（遵循提交规范）
git commit -m "fix: 修复XXX错误模式

- 问题：XXX
- 原因：XXX
- 修复：XXX
- 测试：新增测试用例test_xxx"

步骤4：同步到项目

# 切换到主分支
git checkout main

# 合并分支
git merge feature/你的功能名称

# 推送（如果有远程）
git push origin main

---

📝 提交规范

提交类型

类型	用途	示例
feat	新功能	feat: 新增山东规则
fix	Bug修复	fix: 修正浙江模式检测
docs	文档更新	docs: 更新README
style	代码格式	style: 格式化Python
refactor	重构	refactor: 优化检查逻辑
test	测试相关	test: 新增湖南测试用例
chore	其他	chore: 更新gitignore

提交信息格式

<类型>: <简短描述>

<详细说明（可选）>

- <变更点1>
- <变更点2>
- <测试情况>

示例

# 好的提交
git commit -m "feat: 新增山西规则支持

- 添加山西省到PROVINCE_RULES
- 包含院校专业组模式45个志愿
- - - - - - - - - - - - - - - - - - -
测试：本地测试通过
数据：待官方核实"

# 不好的提交
git commit -m "修改了一些内容"

---

🎯 贡献类型详解

添加新省份

1. 编辑规则文件

   # skills/gaokao-spec-checker/scripts/spec_checker_v2.py
   PROVINCE_RULES["新省份"] = {
       "mode": "院校专业组",
       "max_volunteers": 45,
       "max_majors_per_group": 6,
       ...
   }
   

2. 添加文档

   # rules/provinces/新省份.md
   
   ## 山西省2026年高考规则
   
   - 志愿数：45个
   - 模式：院校专业组
     ...
   

3. 添加测试

   # tests/cases/新省份-XXX.md
   - 标准方案
   - 错误方案
   

4. 更新说明

   • CHANGELOG.md
   • README.md（省份列表）

发现新错误模式

1. 记录错误

   # rules/errors/ERRORS.md
   
   ### E###：<错误名称>
   
   - **症状**：<描述>
   - **正确**：<应该是>
   - **场景**：<何时出现>
   - **修复**：<如何修正>
   - **首次发现**：YYYY-MM-DD
   - **报告人**：@用户名
   

2. 更新检查器（如果需要代码检测）

   # skills/gaokao-spec-checker/scripts/spec_checker_v2.py
   # 在_check_xxx方法中添加检测逻辑
   

3. 添加测试

   # 在tests/test_all.py中添加测试函数
   

真实案例

1. 复制模板

   cp docs/case-studies/TEMPLATE.md \
      docs/case-studies/case-###.md
   

2. 填写案例

   ## 案例###：<简述>
   
   **咨询时间**：YYYY-MM-DD
   
   **用户信息**：...
   **方案生成**：...
   **后续动作**：...
   **教训总结**：...
   

---

🧪 测试要求

提交前必须

• 所有自动化测试通过
• 手动测试通过
• 文档已更新
• 提交信息符合规范

运行测试

# 全部测试
python3 tests/test_all.py

# 单省份测试
python3 skills/gaokao-spec-checker/scripts/spec_checker_v2.py

# 手动验证
python3 ~/.local/bin/gaokao-checker tests/cases/hunan-578.md

---

🎨 代码规范

Python规范

• 遵循 PEP 8
• 函数必须有 docstring
• 关键逻辑添加中文注释
• 类型提示（Python 3.10+）

Markdown规范

• 标题层次清晰
• 表格对齐
• 代码块标注语言

命名规范

• 目录：lowercase-hyphen
• 文件：lowercase_underscore 或 lowercase-hyphen
• 类：PascalCase
• 函数/变量：snake_case

---

📞 联系方式

报告问题

• 在文件中记录错误模式
• 提交PR修复
• 更新FAQ

讨论功能

• 在优化日志中记录
• 更新未来规划
• 提交讨论Issue

---

📜 行为准则

我们欢迎

• ✅ 建设性的批评
• ✅ 真诚的建议
• ✅ 真实的案例
• ✅ 严谨的态度

我们不接受

• ❌ 人身攻击
• ❌ 虚假信息
• ❌ 不专业的态度
• ❌ 数据造假

---

🏆 贡献者荣誉

贡献类型

类型	说明	标记
错误发现	发现新错误模式	🔍
代码贡献	修复Bug/新功能	💻
文档编写	完善文档	📝
案例分享	真实咨询案例	📖
测试验证	测试和验证	✅

---

感谢每一位贡献者！

---

版本: v2.0
最后更新: 2026-06-11