Trail of Bits publications 仓库贡献指南：从读懂目录结构到提交第一个 PR

【免费下载链接】publicationsPublications from Trail of Bits项目地址: https://gitcode.com/GitHub_Trending/pu/publications

publications 是 Trail of Bits 的公开出版物归档仓库，收录安全审查报告、会议演讲、论文与数据集。读完这篇 publications 贡献指南，你可以独立走通完整闭环：看懂仓库结构、在本地验证表格渲染、挑一个合适的任务，并交出一个符合仓库规矩的第一个 PR。

里程碑一 · 先看懂它：这个仓库到底存了什么？

一句话定位：这里没有代码，只有一份 1300 多行的 README.md 当目录索引，加上一堆 PDF 和幻灯片——你几乎所有的贡献，都是"放好文件 + 在表格里加一行"。

/ai_maturity_matrix.png?utm_source=gitcode_repo_files)

图：presentations/下归档的演讲素材示例——你的任务就是让这类文件在 README 表格里有迹可循

里程碑二 · 本地跑通：没有构建脚本，怎么算跑起来了？

环境要求：git 和一个能预览 Markdown 的编辑器（VS Code 自带）。不需要安装任何依赖。

git clone https://gitcode.com/GitHub_Trending/pu/publications

克隆仓库到本地。

cd publications && git checkout -b add/my-first-review

从 master 拉一个自己的分支。仓库规矩是"所有修改走新分支 + PR，永不直接提交到 master"。

怎么确认环境搭好了？两个成功信号：

1. 在编辑器里打开README.md开 Markdown 预览：表格应整齐渲染，点一个 📄 图标能跳到对应 PDF，说明相对路径没断。
2. 终端里对任意一张审查表做列对齐检查，例如 Ethereum/EVM 一节：

sed -n '/^#### Ethereum\/EVM$/,/^####/p' README.md | grep '^|' | awk -F'|' '{print NF}' | sort -u

它统计该节所有表格行的字段数，输出应该只有一个数字——意味着每行列数一致。如果蹦出好几个数字，说明这张表里混进了截断行，你的眼睛已经能发现问题了，这就是"跑通"。

里程碑三 · 选任务：第一个任务去哪里找？

任务来源就是仓库的 issues 和标签。这个仓库的典型任务长这样：

• 加一条新审查报告：客户同意公开后，把 PDF 放进reviews/，在对应分类表格加一行
• 归档一场演讲：presentations/下建目录、写带 frontmatter 的README.md、在根表格加一行
• 格式修复：某行月份写成了 "September"、某行少一个竖线、条目排序乱了

选题判断标准，三条都满足再动手：

1. 范围小：改动不超过"1 个文件 + 一两行表格"，需要新增整节的大任务留到后面
2. 描述清晰：issue 里能直接拿到文件名、作者、日期、公告链接，不用猜
3. 与现有结构耦合低：不需要挪动章节顺序、不需要同步更新文件头部的目录

动手前先确认这条记录是否真的该公开：仓库里大量审查属于 confidential，issue 没明确说"可公开"就先别做，问一句比返工便宜。

里程碑四 · 开发与自检：Markdown 表格有哪些暗规矩？

这个仓库的"代码规范"全写在 CLAUDE.md 里，挑最容易踩的几条：

• 月份一律 3 字母缩写Jan–Dec，禁止September，也禁止 4 字母的Sept
• 审查表固定 5 列，每行必须恰好 6 个|，缺数据的列用空单元格| |补齐，不许截断
• Product 列只写干净的产品名：不带 "Security Review""Protocol" 这类后缀，冗长名字要缩短
• 文档图标有分工：📄 评估报告、✅ 修复复审、🔖 公证函、📛 威胁模型；同一产品的多个文档挤在同一行，图标之间不留空格
• 演讲目录只以演讲标题命名，不带会议名；目录内必须有带 YAML frontmatter（title/date/authors/conference/resources）的README.md
• 各节内部按日期从新到旧排序；改格式时永不顺手修改 URL 或文件路径

避坑：最危险的操作是"顺手规范化"——把相邻行的日期、空格也一起改掉，diff 会突然变大。维护者要的是最小改动，你的第一份 PR 尤其如此。

提交前自检清单

• 每行表格的|数量与表头一致，空单元格是| |
• 日期全是 3 字母月份，小数写作0.2而不是.2
• 新条目插在对应节的最前面（最新的在最上），且没有重复条目
• 演讲目录的README.mdfrontmatter 字段齐全
• diff 里没有任何"顺手修好"的 URL、路径或相邻行

里程碑五 · 交出去：PR 写什么，review 怎么接？

提交信息：看 git log，历史提交都是add report and update readme这种直白风格。沿用add:/fix:前缀即可，例如：

git commit -m "add: scroll euclid phase 2 security review entry"

一行说清加了什么、动了哪张表，比长段落好使。

PR 描述三句话就够：改了什么（哪个分类、哪个条目）、依据（issue 编号）、怎么验证的（例如"已确认 Ethereum/EVM 表全部行字段数一致，日期按从新到旧排列"）。

review 应对：维护者最常见的意见是格式问题。假设有人留言"Product 列太长了，参考 CLAUDE.md 里 Product Column Formatting 那段"，可以这样回：

收到，我把Offchain Labs Custom Fee ERC-20 Bridge Upgrade and EIP-7702 Fixes缩成Offchain Custom Fee Bridge & EIP-7702，去掉冗余后缀，马上提交。

具体引用对方指出的规则 + 给出你的改法，比回一个"OK 已修改"高效得多。

下一步

第一个 PR 不追求惊艳，追求"零返工"：挑一条加审查报告的 issue，按里程碑四的清单过一遍，交出去。仓库规矩在 CLAUDE.md，条目格式对着 README.md 里同类表格抄，任务去 issues 的 "good first issue" 标签下翻。你缺的不是技能，是一次动手。

【免费下载链接】publicationsPublications from Trail of Bits项目地址: https://gitcode.com/GitHub_Trending/pu/publications