Python PEP 8 + GitHub 流程考核（操作题）

本仓库用于“编程操作题”考试：考察候选人对 Python 基本代码规范（PEP 8 思想） 与 GitHub 基础协作流程（分支 / 提交 / PR） 的掌握。

一、考试目标

你需要在 不改变既有功能/输出 的前提下，修复仓库中的代码规范问题，使其通过 CI 的自动检查。

CI 会检查：

• Python 代码质量（ruff）
• 格式化（black --check）
• 导入排序（isort --check-only）
• 单元测试（pytest）
• 基础提交信息规范（可选：本仓库版本不在 CI 中强制检查提交信息，但会在人工复核中查看）

二、任务要求（必须全部完成）

1. 创建新分支：从 main 创建分支，命名建议(请将user替换为实际的用户名)：fix/user 或 task/user-fix。
2. 修复代码规范问题：
   • 修复 src/bad_style.py 里的 PEP 8/可读性问题（命名、导入、空格、长行、文档字符串、异常、重复代码等）
   • 允许你拆分函数、增加辅助函数、增加类型注解、增加合理注释/Docstring
   • 不得修改程序对外行为：单元测试应全部通过
3. 提交并推送：
   • 进行至少 1 次 commit（建议 1~3 次，小步提交）
   • 提交信息建议格式：fix: make code pep8 compliant（也可使用你们团队规范）
4. 发起 Pull Request：
   • ⚠️ 注意：本仓库禁止直接推送到 main 分支，所有更改必须通过 PR 提交
   • 推送分支后，系统会自动创建 PR（或手动创建）
   • PR 标题清晰说明做了什么
   • PR 描述中写明：你修复了哪些类型的问题（例如：imports/formatting/naming/docstring）
   • 等待 GitHub Actions 自动运行所有检查

三、通过标准

• GitHub Actions 绿灯（全部 job 通过）
• PR 内容清晰、可读
• 不引入功能回归（pytest 通过）

📋 自动化功能

本仓库已配置以下自动化功能：

✅ 自动 PR 检测

• 当你推送分支后，系统会自动创建 Pull Request
• PR 会自动触发 CI 检查（ruff、black、isort、pytest）
• 检查结果会显示在 PR 页面，全部通过后显示绿色 ✅

🔒 Main 分支保护

• 禁止直接推送到 main 分支
• 所有代码更改必须通过 Pull Request 提交
• 详细的分支保护规则请参考 BRANCH_PROTECTION.md

四、本地运行建议

1、创建环境（建议使用 Python 3.11）

conda create --name myenv python=3.11 -y
conda activate myenv

2、从 main 拉出分支：

git checkout -b fix/pep8
修改 src/bad_style.py（或题目指定文件），修复规范问题但不改行为

pip install -r requirements.txt

3、运行测试
python -m pytest -q tests/

# 运行静态检查（与 CI 一致）
ruff check .
black --check .
isort --check-only .

4、推送并创建 PR：
git add .
git commit -m "fix: pep8 refactor"
git push -u origin fix/user （请将user替换为实际的用户名）

# ✅ 系统会自动创建 PR
# 在 GitHub 网站上查看 PR 页面，等待 GitHub Actions 执行
# 看到 grading-ci / grade (lint + format + tests) 为绿色即通过
# ⚠️ 注意：不要直接推送到 main 分支，必须通过 PR 合并

五、评分建议

• 60%：CI 是否通过（ruff/black/isort/pytest）
• 20%：代码可读性（命名、函数长度、注释与 docstring 是否合理）
• 20%：GitHub 流程规范（分支、提交粒度、PR 描述）