CONTRIBUTING.md

Contributing Guide

感谢你愿意帮助完善这个仓库。

这个项目的目标不是堆很多大模型名词，而是做成一个对初学者真正友好、能在单卡 RTX 5080 16GB 上跑通关键流程、同时兼顾原理和工程实践的 Notebook 学习仓库。

如果你也认同这个目标，非常欢迎你一起补内容、修文档、改 notebook、补示例。

先理解项目定位

在开始改之前，建议先看这几个文件：

• README.md
• docs/frontier_algorithm_tracker.md
• notebooks/01_environment_setup.ipynb
• notebooks/07_post_training_overview.ipynb

它们能帮你快速理解：

• 这个仓库现在分成哪几条学习路线
• 哪些内容属于基础线，哪些内容属于进阶线或前沿扩展
• 为什么我们始终强调单卡 RTX 5080 16GB

最欢迎的贡献类型

如果你不知道从哪里开始，优先考虑这些方向：

• 修正文档里不够清楚、对初学者不友好的表达
• 补 notebook 里的“手动推导”解释，让原理更容易懂
• 优化 notebook 里的默认参数，让单卡 16GB 更稳
• 增加小规模、可直观看到结果变化的 demo
• 更新前沿追踪文档中的官方链接、定位和学习建议
• 修复 notebook 的代码语法、JSON 结构或运行顺序问题

第一次参与，最稳的三条起步路线

如果你是第一次给这个仓库提 issue 或 PR，最推荐先从“小而清楚、容易验证”的改动开始。

路线 1：先做文档澄清

最适合你遇到这些情况时开始：

• 你能看懂内容，但觉得某一段解释对初学者不够友好
• 你发现 README、展示文档、notebook 小节标题可以更顺
• 你觉得某张展示卡片值得补一句更直白的图注

很适合的第一类改动例子：

• 给 README.md 某段加一句“这一步到底会看到什么”
• 给 docs/showcase_capture_guide.md 补一条更清楚的截图建议
• 给某本 notebook 的手动推导部分补一小段“为什么这样算”

如果你准备先提 issue，优先使用：

• Notebook improvement

路线 2：先做单卡 16GB 友好改进

最适合你遇到这些情况时开始：

• 某个默认参数第一次就太激进
• 某段 demo 能跑，但对单卡 RTX 5080 16GB 不够稳
• 你发现一个更保守但仍能看到结果的起点

很适合的第一类改动例子：

• 把某个 demo 的 max_steps、batch size、max_length 调成更稳的默认值
• 给某段训练前补一句“显存紧张先按什么顺序降参数”
• 报告某个 notebook 在单卡环境下的具体报错或不一致现象

如果你准备先提 issue，优先使用：

• Notebook improvement
• Bug report

路线 3：先做前沿追踪补充

最适合你遇到这些情况时开始：

• 你发现某个方向有新的官方文档、官方仓库或论文页
• 你觉得某条前沿路线值得补进追踪文档，但不适合立刻塞进主线 notebook
• 你能分清它更适合“单卡教学实践”还是“阅读跟进”

很适合的第一类改动例子：

• 给 docs/frontier_algorithm_tracker.md 补一条新的一手来源
• 给某个前沿项目补“具体日期 + 为什么重要 + 对本仓库怎么承接”
• 修正某条前沿链接或补更准确的官方入口

如果你准备先提 issue，优先使用：

• Frontier update

第一次参与时，不太建议一上来就做的事

这些事不是永远不能做，而是通常不适合作为第一步：

• 一次改很多本 notebook
• 同时重写 README、目录结构和环境说明
• 为了追热点直接新增重型依赖或默认多卡路径
• 还没验证单卡 16GB 边界，就把 demo 步数、长度、batch 调大
• 只补新术语，不解释它和现有 01-15 主线的关系

一个很实用的判断标准是：

• 第一次 PR 最好只解决一个主要问题
• reviewer 看完后，能用两三句话说清“你到底改好了什么”

第一次提 issue，最短怎么写

如果你还不想一下子写很完整，也没关系。对这个仓库来说，先把下面这 4 件事写清楚，通常就已经足够让别人开始帮你排查：

1. 发生在哪个文件、哪本 notebook、哪一节
2. 你做到哪一步，或者改了哪些关键参数
3. 你实际看到了什么现象、输出或报错
4. 你原本预期看到什么

如果问题和单卡 RTX 5080 16GB 运行边界有关，建议再补这几个最关键的配置：

• batch size
• max_steps
• max_length / max_completion_length
• 是否量化、是否 LoRA、是否只跑手动部分

你甚至可以直接照着下面这几行最短模板写：

文件 / notebook：
运行到哪一步：
实际现象 / 报错：
预期现象：
关键配置（可选）：

这类最短 issue 往往比很长但没有重点的日志更容易被快速处理。

可直接复制的 3 个最小示例

如果你第一次提 issue 时还不想自己想措辞，可以先从下面这三类最小示例开始改。

示例 1：Bug report

文件 / notebook：`notebooks/01_environment_setup.ipynb`
运行到哪一步：GPU 检查那一格
实际现象 / 报错：`torch.cuda.is_available()` 返回 `False`，但 `nvidia-smi` 能看到显卡
预期现象：在单卡 `RTX 5080 16GB` 环境下，默认环境检查应该识别到 GPU
关键配置（可选）：Python 版本、torch 版本、是否在 `.venv` 或 conda 环境里运行

示例 2：Notebook improvement

你想改进哪个 notebook：`notebooks/11_ppo_alignment.ipynb`
你觉得现在的问题是什么：手动 advantage / ratio 的计算和后面的 `PPOTrainer` demo 接得有点快
你的建议改法：在手动 toy 计算后面补一张“手动变量 -> trainer 中对应概念”的对照表
这项改动为什么对初学者更有帮助：这样更容易把手算结果和调包接口真正对上
是否会影响单卡 `RTX 5080 16GB` 默认边界：不会

示例 3：Frontier update

方向：RL / Post-training
项目 / 论文 / 技术报告名称：SDPO / Self-Distillation Policy Optimization
一手来源链接：TRL `SDPOTrainer` 文档、`arXiv:2601.20802`
具体日期：论文提交日期 `2026-01-28`
为什么值得加入：它说明 `PPO -> GRPO -> GSPO -> SDPO` 这条在线 RL 变体主线还在继续增长
建议放在哪：先更新 `docs/frontier_algorithm_tracker.md`，暂时不建议直接塞进 `01-15` 主线

这些示例的目的不是限制你怎么写，而是帮你更快迈出第一步。

第一次提 PR，最短怎么写

如果你已经准备从 issue 走到 PR，也不用一下子写得很复杂。对这个仓库来说，第一次 PR 最短先写清这 3 件事，通常就已经足够：

1. 你改了哪些文件
2. 你为什么要改
3. 你实际怎么验证过

如果你的改动和单卡 RTX 5080 16GB 运行边界有关，最好再补一句：

• 默认参数有没有变重
• 有没有破坏“手动原理 + 调包 demo”的双轨节奏
• 如果改了 notebook，是否做过 JSON / AST 校验

你甚至可以直接照着下面这几行最短模板写：

这次改动做了什么：
为什么改：
如何验证：
还有什么要提醒 reviewer：

可直接复制的最小 PR 示例

这次改动做了什么：
- 改了 `README.md`、`CONTRIBUTING.md` 和 PR / issue 模板相关文档
- 补了第一次提 issue / PR 的最小示例
- 让新贡献者更容易开始公开协作

为什么改：
- 当前更高价值的工作不是继续扩 notebook 数量，而是继续降低第一次协作的沟通成本

如何验证：
- 核对 README、CONTRIBUTING、模板文案是否一致
- 确认没有改动 notebook 主线和依赖结构
- 跑了 `git diff --check`

还有什么要提醒 reviewer：
- 这次只改文档和协作模板，没有改 notebook 内容，因此不涉及 `.ipynb` 的 JSON / AST 校验

这类 PR 说明看起来不花哨，但通常已经足够让 reviewer 很快接住上下文。

贡献时要遵守的几条核心规则

1. 代码仍然以 ipynb 为主

这个仓库不是要演化成一个复杂 Python 包。
允许增加少量说明文档，但主要教学逻辑尽量留在 notebook 里。

2. 默认面向单卡 RTX 5080 16GB

新增内容时请优先问自己：

• 这个默认配置会不会太重？
• 有没有更小模型、更小数据、更短训练步数也能说明问题？
• 能不能先做 toy demo，再给出更真实的调包版本？

3. 保留“双轨教学”

高价值的 notebook 通常同时包含两部分：

• 手动理解：把公式、loss、张量变化拆开
• 调包实践：用 transformers、peft、trl 等库快速看到结果

如果只剩“调包”，初学者容易看不懂。
如果只剩“公式”，初学者又很难建立工程直觉。

4. 不要为了追热点破坏主线

前沿算法可以补，但不要让它冲掉基础线 01-06 或进阶线 07-12 的清晰结构。

如果一个新方向更适合阅读跟进，而不适合单卡教学复现，优先补进：

• docs/frontier_algorithm_tracker.md

而不是直接塞进主线 notebook。

notebook 编辑建议

每本核心 notebook 尽量沿用统一节奏：

背景与目标 -> 手动推导 -> toy 计算 -> 调包 demo -> 结果对照 -> 常见坑 -> 小结 / 练习

新增 notebook 时，也尽量保持这个节奏。

提交前建议做的检查

1. 检查 notebook 是否还是合法 JSON

python3 - <<'PY'
import json
from pathlib import Path
for path in Path('notebooks').glob('*.ipynb'):
    json.loads(path.read_text(encoding='utf-8'))
print('all notebook json ok')
PY

2. 检查 code cell 语法

python3 - <<'PY'
import ast, json
from pathlib import Path

for path in Path('notebooks').glob('*.ipynb'):
    data = json.loads(path.read_text(encoding='utf-8'))
    for cell in data.get('cells', []):
        if cell.get('cell_type') != 'code':
            continue
        source = ''.join(cell.get('source', []))
        cleaned = []
        for line in source.splitlines():
            stripped = line.lstrip()
            if stripped.startswith('!') or stripped.startswith('%'):
                continue
            cleaned.append(line)
        code = '\n'.join(cleaned).strip()
        if code:
            ast.parse(code)
print('all code cells ast ok')
PY

3. 再检查一遍这次改动有没有破坏初学者体验

特别看这几个点：

• notebook 标题和学习路径是否还清楚
• 默认参数是否仍适合单卡 16GB
• 是否讲清楚“为什么这样做”
• 是否让读者更容易上手，而不是更容易迷路

关于 git

这个项目当前默认采用本地 git 增量管理。

建议保持：

• 小步提交
• commit message 说明“这次为什么改”
• 不要为了整理历史去强推、改写历史

如果你是在 GitHub 页面上协作，仓库里也已经补了：

• .github/ISSUE_TEMPLATE/
• .github/PULL_REQUEST_TEMPLATE.md
• .github/workflows/notebook-structure-check.yml

它们会提醒贡献者尽量说明：

• 改动影响的是哪条学习路线
• 是否仍然符合单卡 RTX 5080 16GB 的默认边界
• 是否做过 notebook 的 JSON / AST 检查

很适合补的未来方向

如果你想补新内容，但又不想破坏主线，当前更推荐的思路不是“继续快速加很多 notebook”，而是先问自己：

• 这个新方向是否真的适合单卡 RTX 5080 16GB
• 它是否比现在已有的 13-15 前沿扩展更有教学价值
• 它是否能继续保持“手动原理 + 调包 demo”的双轨节奏

这些方向已经在 docs/frontier_algorithm_tracker.md 里有上下文，不需要从零起步。

最后

这个仓库希望给人的感觉不是“很炫”，而是“真能学明白”。
如果你的改动能让一个初学者少走很多弯路，那就是非常高价值的贡献。