Skip to content

Commit eee48af

Browse files
SWHLSWHL
committed
docs: update contributing
1 parent 6b8a9aa commit eee48af

1 file changed

Lines changed: 225 additions & 26 deletions

File tree

‎docs/contributing.md‎

Lines changed: 225 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,62 +6,261 @@ hide:
66
- toc
77
---
88

9+
感谢你对 Rapid Layout 的关注与贡献！本文档说明如何参与项目的代码开发与文档贡献，包括环境准备、开发流程和提交流程。
910

10-
感谢你对 Rapid Layout 的关注与贡献！欢迎通过以下方式参与项目。
11+
## 前置要求
1112

12-
## 贡献方式
13+
- Python >= 3.6（推荐 3.8+）
14+
- Git
15+
- 已注册的 GitHub 账号
1316

14-
### 反馈问题与建议
17+
---
1518

16-
- **Bug 反馈**：在 [Issues](https://github.com/RapidAI/RapidLayout/issues) 中提交 Bug 报告，请尽量包含复现步骤、环境信息与报错信息。
17-
- **功能建议**：在 Issues 中使用 Feature Request 模板描述你的需求或使用场景。
18-
- **文档与示例**：发现文档错误或希望补充示例时，可直接提 Issue 或 PR。
19+
## 一、克隆源码
20+
21+
从 Rapid Layout 主仓库克隆项目到本地：
1922

20-
### 提交代码（Pull Request）
23+
```bash
24+
git clone https://github.com/RapidAI/RapidLayout.git
25+
cd RapidLayout
26+
```
2127

22-
1. **Fork 本仓库**，并在本地克隆你 Fork 后的仓库。
23-
2. **创建分支**：从 `main` 拉取最新代码，建议使用独立分支进行修改，例如 `git checkout -b fix/xxx` 或 `feature/xxx`。
24-
3. **开发与自测**：在本地完成修改与测试，确保不破坏现有行为。
25-
4. **提交 PR**：将分支推送到你的 Fork，在 [RapidLayout](https://github.com/RapidAI/RapidLayout) 仓库中发起 Pull Request，并简要说明改动内容与原因。
28+
若网络受限，可先 Fork 到个人账号后再克隆（见后文「准备提交」部分）。
2629

27-
我们会尽快 Review，必要时会与你讨论修改建议。
30+
---
2831

29-
## 开发环境
32+
## 二、配置开发环境
3033

31-
### 环境准备
34+
建议使用虚拟环境，避免与系统 Python 冲突：
3235

33-
```bash linenums="1"
34-
git clone https://github.com/RapidAI/RapidLayout.git
35-
cd RapidLayout
36+
```bash
37+
# 使用 venv
38+
python -m venv .venv
39+
source .venv/bin/activate # Linux/macOS
40+
# .venv\Scripts\activate # Windows
41+
42+
# 或使用 conda
43+
conda create -n rapidlayout python=3.10
44+
conda activate rapidlayout
45+
```
46+
47+
安装依赖（开发时建议可编辑安装以便本地修改生效）：
48+
49+
```bash
3650
pip install -r requirements.txt
51+
pip install pytest # 运行单元测试需要
3752
pip install -e .
3853
```
3954

40-
### 代码规范
55+
如需使用 ONNX Runtime 等推理后端，请按 [安装文档](https://rapidai.github.io/RapidLayout/install_usage/installation/) 安装对应依赖。
56+
57+
---
4158

42-
项目使用 [black](https://github.com/psf/black) 做代码格式化，并配合 pre-commit 做提交前检查。建议在本地安装 pre-commit：
59+
## 三、安装代码格式化与 pre-commit 钩子
4360

44-
```bash linenums="1"
61+
在已激活的虚拟环境中安装 pre-commit，并在**仓库根目录**启用 Git 提交前钩子，以便自动做代码格式检查与整理（如 black、autoflake 等）：
62+
63+
```bash
4564
pip install pre-commit
4665
pre-commit install
4766
```
4867

49-
提交前会自动执行 `autoflake`（清理未使用导入与变量）和 `black` 格式化，请确保修改后的代码通过上述检查。
68+
安装成功后，每次执行 `git commit` 时会自动运行配置好的格式化工具；若检查未通过，提交会被拒绝，请根据提示修改后再次提交。也可在提交前手动跑一遍：
69+
70+
```bash
71+
pre-commit run --all-files
72+
```
73+
74+
---
75+
76+
## 四、运行单元测试
77+
78+
在**仓库根目录**下执行：
79+
80+
```bash
81+
# 运行全部测试
82+
pytest tests/ -v
83+
84+
# 仅运行部分测试文件
85+
pytest tests/test_main.py -v
86+
87+
# 查看测试覆盖率（需先安装 pytest-cov）
88+
pytest tests/ -v --cov=rapid_layout
89+
```
90+
91+
确认当前主分支在你本机环境下测试通过，再进行修改。
92+
93+
---
94+
95+
## 五、复现问题 / 增加新功能
96+
97+
### 反馈问题与建议
98+
99+
- **Bug 反馈**：在 [Issues](https://github.com/RapidAI/RapidLayout/issues) 中提交 Bug 报告，请尽量包含复现步骤、环境信息与报错信息。
100+
- **功能建议**：在 Issues 中使用 Feature Request 模板描述你的需求或使用场景。
101+
- **文档与示例**：发现文档错误或希望补充示例时，可直接提 Issue 或 PR。
102+
103+
### 复现 Bug
104+
105+
1. 在 [Issues](https://github.com/RapidAI/RapidLayout/issues) 中选定或创建对应 issue。
106+
2. 根据 issue 描述与报错信息，在本地用仓库代码复现问题。
107+
3. 在 `rapid_layout/` 或 `tests/` 下定位并修改代码，直到问题消失。
108+
109+
### 增加新功能
110+
111+
1. 与 maintainer 或现有 issue 讨论需求与实现方式（可选但推荐）。
112+
2. 在 `rapid_layout/` 下实现新逻辑，保持与现有代码风格一致（项目使用 [black](https://github.com/psf/black) 等规范）。
113+
3. 新功能应有对应单元测试覆盖。
114+
115+
---
116+
117+
## 六、编写对应单元测试
118+
119+
- 测试文件放在 **`tests/`** 下，命名建议 `test_*.py`。
120+
- 使用 **pytest** 编写用例，可参考现有 `test_main.py`。
121+
- 测试用图片等资源放在 `tests/test_files/`。
122+
- 新增测试应：
123+
- 能稳定复现你要验证的行为（Bug 修复或新功能）；
124+
- 不依赖未在仓库或文档中说明的外部服务（必要时用 mock 或跳过）。
125+
126+
示例：
127+
128+
```python
129+
# tests/test_xxx.py
130+
import pytest
131+
from pathlib import Path
132+
133+
cur_dir = Path(__file__).resolve().parent
134+
root_dir = cur_dir.parent
135+
test_dir = cur_dir / "test_files"
136+
137+
def get_engine():
138+
from rapid_layout import RapidLayout
139+
return RapidLayout()
140+
141+
def test_your_new_feature():
142+
engine = get_engine()
143+
img_path = test_dir / "layout.jpg"
144+
result = engine(img_path)
145+
assert result is not None
146+
# 更多断言...
147+
```
148+
149+
---
150+
151+
## 七、运行所有单元测试
152+
153+
在**仓库根目录**下再次全量跑测，确保无回归：
154+
155+
```bash
156+
pytest tests/ -v
157+
```
158+
159+
若有测试被跳过（如缺少某推理引擎），请确认你修改或新增的测试在现有环境下已执行并通过。
160+
161+
---
162+
163+
## 八、准备提交到仓库
164+
165+
### 8.1 Fork Rapid Layout 主仓库到个人账号
166+
167+
1. 打开 [Rapid Layout 主仓库](https://github.com/RapidAI/RapidLayout)。
168+
2. 点击右上角 **Fork**，将仓库 fork 到你自己的 GitHub 账号下（例如 `https://github.com/你的用户名/RapidLayout`）。
169+
170+
### 8.2 将代码提交到个人 Fork
171+
172+
若最初是克隆的主仓库，需要添加你的 fork 为远程，并推送到 fork：
173+
174+
```bash
175+
# 在项目根目录 RapidLayout 下执行
176+
git remote add myfork https://github.com/你的用户名/RapidLayout.git
177+
# 若已有 origin 且就是主仓库，可保留；推送时用 myfork
50178

51-
### 文档本地预览
179+
# 创建分支（推荐为每个 issue/功能单独分支）
180+
git checkout -b fix/xxx # 或 feat/xxx、docs/xxx
181+
182+
# 添加并提交修改
183+
git add .
184+
git status # 确认只提交预期文件
185+
git commit -m "fix: 简短描述"
186+
187+
# 推送到你的 fork
188+
git push myfork fix/xxx
189+
```
190+
191+
**请按约定式提交规范（Conventional Commits）书写 commit 信息**，便于维护者阅读与自动生成 Changelog。格式为：
192+
193+
```text
194+
<类型>[可选范围]: <简短描述>
195+
196+
[可选正文]
197+
[可选脚注]
198+
```
199+
200+
常用类型示例：
201+
202+
| 类型 | 说明 |
203+
|------------|------------------------|
204+
| `feat` | 新功能 |
205+
| `fix` | Bug 修复 |
206+
| `docs` | 文档变更 |
207+
| `style` | 代码格式（不影响逻辑） |
208+
| `refactor` | 重构 |
209+
| `test` | 测试相关 |
210+
| `chore` | 构建/工具等 |
211+
212+
示例：`fix: 修复某条件下版面结果为空`、`feat: 支持 xxx 输入格式`、`docs: 更新安装说明`。
213+
214+
### 8.3 向 Rapid Layout 主仓库提交 Pull Request（PR）
215+
216+
1. 打开你 fork 后的仓库页面（如 `https://github.com/你的用户名/RapidLayout`）。
217+
2. 若刚推送分支，页面上通常会出现 **Compare & pull request**，点击即可；否则在 **Branches** 里选择你刚推送的分支，再点 **New pull request**。
218+
3. 确认 **base 仓库** 为 `RapidAI/RapidLayout`、**base 分支** 为 `main`（或仓库默认主分支），**head 仓库** 为你的 fork、**head 分支** 为你的分支（如 `fix/xxx`）。
219+
4. 填写 PR 标题和说明：
220+
- 标题：简要概括修改内容（如「Fix: 修复 xxx 问题」）。
221+
- 说明中建议包含：
222+
- 对应 Issue 编号（若有）：`Fixes #123` 或 `Related to #123`。
223+
- 修改原因与主要改动。
224+
- 如何验证：例如「在仓库根目录执行 `pytest tests/ -v` 通过」。
225+
5. 提交 PR，等待 maintainer 审查；根据反馈再在本地修改并推送同一分支，PR 会自动更新。
226+
227+
---
228+
229+
## 流程小结
230+
231+
| 步骤 | 说明 |
232+
|------|------|
233+
| 1 | 克隆 Rapid Layout 源码 |
234+
| 2 | 配置虚拟环境并安装依赖与 pytest，可编辑安装 `pip install -e .` |
235+
| 3 | 安装 pre-commit（`pip install pre-commit`），在仓库根目录执行 `pre-commit install` |
236+
| 4 | 运行单元测试（`pytest tests/ -v`），确认基线通过 |
237+
| 5 | 复现问题或实现新功能 |
238+
| 6 | 编写/补充对应单元测试 |
239+
| 7 | 在仓库根目录运行全部测试并确认通过 |
240+
| 8 | Fork 主仓库到个人账号 |
241+
| 9 | 按约定式提交规范编写 commit，将修改提交并推送到个人 Fork 的对应分支 |
242+
| 10 | 在主仓库创建 PR，从个人 Fork 分支指向主仓库 main |
243+
244+
---
245+
246+
## 文档本地预览
52247

53248
修改 `docs/` 下内容后，可使用 MkDocs 本地预览：
54249

55-
```bash linenums="1"
56-
pip install -r requirements.txt
250+
```bash
251+
pip install mkdocs mkdocs-material
57252
mkdocs serve
58253
```
59254

60255
在浏览器中打开提示的地址（一般为 `http://127.0.0.1:8000`）即可查看效果。
61256

257+
---
258+
62259
## 其他说明
63260

64-
- 提交 Issue 或 PR 时，请使用清晰、简洁的标题与描述，便于维护者处理。
65-
- 若你希望参与长期维护或较大功能开发，欢迎在 Issue 中说明，我们会与你沟通协作方式。
261+
- **代码风格**：项目采用 [black](https://github.com/psf/black)、autoflake 等规范，已通过 pre-commit 钩子在提交时自动检查；也可在仓库根目录执行 `pre-commit run --all-files` 手动跑一遍。
262+
- **文档**：更多安装与使用说明见 [Rapid Layout 文档](https://rapidai.github.io/RapidLayout/)。
263+
- **问题与讨论**：Bug 与功能建议可通过 [GitHub Issues](https://github.com/RapidAI/RapidLayout/issues) 反馈。
264+
- 提交 Issue 或 PR 时，请使用清晰、简洁的标题与描述，便于维护者处理。若你希望参与长期维护或较大功能开发，欢迎在 Issue 中说明，我们会与你沟通协作方式。
66265

67266
再次感谢你的贡献！

0 commit comments

Comments
 (0)