Skip to content

Commit e676267

Browse files
author
William Yang
committed
docs: rewrite README for student-friendly experience
- Simplify README with 30-second quickstart - Focus on essential commands: install, login, check, submit - Add FAQ section for common issues - Move developer content to CONTRIBUTING.md - Hide advanced options in collapsible section README reduced from ~220 lines to ~120 lines
1 parent b9927e9 commit e676267

File tree

2 files changed

+225
-200
lines changed

2 files changed

+225
-200
lines changed

CONTRIBUTING.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing to bootcs-cli
2+
3+
感谢你对 bootcs-cli 的贡献兴趣!本文档面向开发者和贡献者。
4+
5+
## 项目背景
6+
7+
bootcs-cli 基于 [check50](https://github.com/cs50/check50)[lib50](https://github.com/cs50/lib50) 扩展开发,用于 BootCS 平台的代码检查和提交。
8+
9+
> **注意**: 本项目与 CS50 课程本身没有直接关系,仅复用了 check50/lib50 的开源代码。
10+
11+
## 开发环境设置
12+
13+
```bash
14+
# 克隆仓库
15+
git clone https://github.com/bootcs-cn/bootcs-cli.git
16+
cd bootcs-cli
17+
18+
# 创建虚拟环境
19+
python -m venv .venv
20+
source .venv/bin/activate
21+
22+
# 安装开发依赖
23+
pip install -e ".[dev]"
24+
```
25+
26+
## 运行测试
27+
28+
```bash
29+
# 运行单元测试
30+
pytest tests/unit/ -v
31+
32+
# 运行所有测试
33+
pytest
34+
35+
# 运行测试并生成覆盖率报告
36+
pytest --cov=bootcs
37+
```
38+
39+
## 代码风格
40+
41+
```bash
42+
# 格式化代码
43+
black bootcs/
44+
45+
# 代码检查
46+
ruff check bootcs/
47+
```
48+
49+
## 项目结构
50+
51+
```
52+
bootcs-cli/
53+
├── bootcs/
54+
│ ├── __init__.py # 版本信息
55+
│ ├── __main__.py # CLI 入口
56+
│ ├── auth/ # 认证模块
57+
│ │ ├── credentials.py # 凭证存储
58+
│ │ └── device_flow.py # GitHub Device Flow
59+
│ ├── api/ # API 客户端
60+
│ │ ├── client.py # HTTP 客户端
61+
│ │ ├── submit.py # 提交 API
62+
│ │ └── checks.py # 远程 checks 管理
63+
│ ├── check/ # 检查模块 (基于 check50)
64+
│ │ ├── _api.py # 检查 API
65+
│ │ ├── runner.py # 检查运行器
66+
│ │ └── c.py # C 语言支持
67+
│ └── lib50/ # 工具库 (基于 lib50)
68+
│ ├── config.py # YAML 配置加载
69+
│ └── ...
70+
├── docker/
71+
│ └── Dockerfile # 学员镜像
72+
├── scripts/
73+
│ ├── install-docker.sh # Docker 版安装脚本
74+
│ └── bootcs-wrapper.sh # Docker wrapper
75+
├── tests/
76+
│ ├── unit/ # 单元测试
77+
│ └── checks/ # 测试用 checks
78+
├── pyproject.toml
79+
├── DESIGN.md # 设计文档
80+
└── ROADMAP.md # 路线图
81+
```
82+
83+
## 环境变量
84+
85+
| 变量 | 说明 | 默认值 |
86+
| -------------------- | ----------------------------- | ------------------------------------- |
87+
| `BOOTCS_API_URL` | API 服务地址 | `https://api.bootcs.cn` |
88+
| `BOOTCS_CHECKS_PATH` | 本地 checks 路径 (评测环境用) | - |
89+
| `BOOTCS_CLI_IMAGE` | Docker 镜像 (开发用) | `ghcr.io/bootcs-cn/bootcs-cli:latest` |
90+
91+
## Docker 镜像构建
92+
93+
```bash
94+
# 本地构建
95+
cd docker
96+
docker build -t bootcs-cli:local .
97+
98+
# 测试本地镜像
99+
BOOTCS_CLI_IMAGE=bootcs-cli:local ./scripts/bootcs-wrapper.sh --version
100+
```
101+
102+
## 发布流程
103+
104+
1. 更新 `pyproject.toml` 中的版本号
105+
2. 提交并推送到 main 分支
106+
3. GitHub Actions 自动构建并推送 Docker 镜像
107+
108+
## 许可证
109+
110+
本项目基于 GPL-3.0 许可证发布,遵循 check50/lib50 的许可证要求。
111+
112+
## 致谢
113+
114+
本项目基于以下开源项目:
115+
116+
- [check50](https://github.com/cs50/check50) - CS50 代码检查工具
117+
- [lib50](https://github.com/cs50/lib50) - CS50 工具库
118+
119+
感谢 CS50 团队的开源贡献!

0 commit comments

Comments
 (0)