Joplin GSoC 2024 Pull Request 规范解读以单 PR 纪律与强制测试约束开源贡献流程【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin本文基于 Joplin 仓库中 GSoC 2024 Pull Request 准则逐条解读 Joplin 在 Google Summer of Code 期间对贡献者提交代码的完整约束从可认领的 issue 来源、单 PR 限制、强制单元测试到禁止 force push 等协作纪律并结合仓库中的测试配置与贡献文档说明每条规则背后的工程理由帮助贡献者一次性提交符合要求的 Pull Request。一、规范定位为什么 GSoC 期间的 PR 规则更严格Joplin 的开发者文档体系位于 readme/dev 目录其中 GSoC 2024 总览页 明确把“如何构建应用、如何贡献、提交 PR 的规则”列为参与者必读内容并将本文档列为核心参考。GSoC 是每年集中涌入大量新贡献者的场景维护者资源有限因此该规范在常规贡献流程之上增加了一组限制性规则。规范开宗明义地说明了动机Due to our limited resources and in order to give everyone a chance to submit a pull request, we have put restrictions in place this year.其目标有二一是保证审查质量二是保证每位贡献者都有机会。值得注意的是这套规则并非孤立存在——仓库通用的贡献文档 readme/dev/index.md 中同样定义了“问题被确认 → 讨论 → 被 triage 标记 → PR 解决共识方案”的四步贡献流程而 GSoC 规范是把这条流程在暑期项目中执行得更加刚性。二、规则 0只处理已被 triage 的 issue规范的第一条编号 0要求贡献者只认领被管理员处理过的 issue——即带有 “high”“medium” 或 “enhancement” 等标签、已经进入 backlog 的 issue。这意味着维护者已经看过该问题并认可其进入开发序列PR 才有被合并的前提。规范给出了四类可选来源按推荐优先级排列修复高优先级或中优先级 bug——这是最被欢迎的入口也是理解代码库的好方式Good First Issue新手友好问题——专门标注给初次贡献者的问题enhancement 特性请求 backlog——其中部分实现复杂、不适合首个 PR另一部分相对简单可以作为切入点在自己的仓库中实现一个 Joplin 插件——评审者会审查插件代码因此应选择不算过于简单的方案以真实展示工程能力插件需要在 Joplin 论坛的 #plugins 分类下发布公告。这条规则与通用贡献文档中的“Contribution scope”一节互为印证readme/dev/index.md 明确指出主要目标是“制造一次贡献”而非解决已被认可问题的 PR 会被关闭不遵循 triage 流程的 PR 可能“在未详细审查的情况下被关闭”。三、禁止认领自己或朋友创建的 issue规范的第二条规定不得处理由自己或自己朋友创建的 issue这类 issue 很可能被直接关闭。其背后的考量与 triage 机制一致——issue 需要由独立于贡献者的维护者来判断价值与方案自己提自己修会绕过这层把关。对于 GSoC 贡献者这意味着选题时应以 issue tracker 中已存在的、由社区或维护者提出的问题为准而不是自拟问题。四、单 PR 纪律每位贡献者同一时间只能有一个 Pull Request规范中最具特色的一条是每位贡献者同一时间只能创建一个 Pull Request待该 PR 合并后才能提交下一个。规范给出了双向理由对维护者如果允许每人多个 PR有限的审查资源无法保证每个 PR 都被认真审查对贡献者只关注一个 PR才能把精力全部投入把它做到最好——“make sure it works well, has test units, documentation and screenshots (if relevant)”。这条规则实际上把贡献流程从“广撒网”导向“单点打磨”与其提交三个半成品不如把一个 PR 打磨到功能正确、附带单元测试、文档和截图如适用齐备。这一原则同样适用于 GSoC 之外GSoC 2024 总览页 在“如何创建第一个 PR”一节也建议新贡献者从一个 high/medium 优先级 bug 或 Good First Issue 起步并提醒不要仅为了修一个错别字而提交 PR。五、严肃问题会被关闭且不给予补救机会规范明确警告如果 PR 存在严重问题、或需要大规模重写才能达到可接受标准维护者可能直接关闭它且贡献者将不被允许重新开启新的 PR。因此“请谨慎提交 PR”please be careful when posting a PR不是套话而是与第 4 条规则联动的机制——由于每次机会只有一次提交前必须确认方案已达成共识对应 triage 标签、实现已完成、测试与文档齐备。这与通用贡献文档中“多个改动混在一个 PR 里大概率会停滞并最终被关闭”的告诫一致进一步支持了“一个 PR 只解决一个问题”的纪律。六、复用代码必须披露规范第五条要求凡是借用borrow他人代码必须在 PR 中披露。规范同时说明这本身是正常甚至被推荐的做法“It is fine and sometimes even recommended to borrow code”但评审者需要据此评估贡献者的实际工作量与理解程度。对 GSoC 评审而言披露程度直接影响对贡献者能力的判断——未披露的复用等同于评估失误因此在描述 PR 内容时应明确列出借鉴来源与自研部分的边界。七、强制单元测试规范的硬性红线规范第六条是硬性要求所有 Pull Request 必须包含单元测试。仅有少数情况如集成测试几乎无法补测试除此之外“我们坚持要求测试如果发现本可以加测试却没加我们可能会关闭该 Pull Request”。规范还给出三条配套指引不知道如何写测试时先到论坛或 Discord 提问如果确实无法添加测试评审阶段会告知贡献者处理方式测试写法参考仓库的 Automated Tests 文档即 readme/dev/index.md 中的对应章节。结合仓库源码可以完整还原 Joplin 的测试体系这正是“测试必须可运行”的含义所在测试框架为 Jest。根 package.json 中的test脚本定义为yarn workspaces foreach --worktree --parallel --verbose --interlaced --jobs 2 run test即按 monorepo workspace 并行调度各包的测试任务。各包继承统一的基础配置。jest.config.base.js 提供了所有jest.config.js继承的基座当前仅watchman: false例如 packages/lib/jest.config.js 在其中追加了testPathIgnorePatterns排除node_modules、rnInjectedJs、vendor目录、testEnvironment: node、slowTestThreshold: 40等参数。一个值得注意的 CI/本地差异packages/lib/jest.config.js 中明确写道由于不要求本地开发者安装 Rust 工具链OneNote 导入器相关测试依赖 Rust 编写的onenote-converter在非 CI 环境未设置IS_CONTINUOUS_INTEGRATION时会被自动跳过。贡献者提交前应在本地能跑通测试的前提下意识到 CI 会执行比本地更完整的测试集。测试文件组织约定新测试以.test.ts后缀放在被测文件同目录如example.ts对应example.test.ts若已存在同名测试文件则直接在其中追加用例。测试工具链packages/lib/testing/test-utils.ts 提供joplin/lib/testing/test-utils包支持搭建带数据库与同步器synchroniser的测试环境Note.test.ts等模型测试是参考范例React Hooks 测试则使用testing-library/react-hooks仓库文档以useLayoutItemSizes.test.ts作为示例。测试粒度要求运行单个文件可用yarn test 文件名运行文件中某个用例可加--filter用例描述单测不足以覆盖时还需提供手工测试计划——至少包含 5 个功能验证用例覆盖 0 个/1 个/10 个/10 万个元素、空字符串/超大字符串等边界输入以及“相关功能未被破坏”的回归验证步骤例如修改了笔记加载逻辑后检查工具栏、笔记切换、标题刷新等相邻功能。这些细节共同说明规范中“必须附测试”并非口号Joplin 的每个包都有可独立运行的 Jest 套件贡献者可以在 packages/lib 这类目录内直接进入yarn test的闭环环境。八、禁止 WIP只接受已完成且可工作的 PR规范第七条规定不接受 Work In Progress进行中状态的 PR只接收“已完成、可工作、带单元测试”的 PRWIP 会直接落入第 3 条规则严重问题关闭且不给予重试机会并被立即关闭。这条规则与单 PR 纪律第四条形成闭环——既然每人只有一个 PR 名额且机会不可挽回把 PR 用作“占坑”或“半成品展示”的空间就被彻底封死贡献者要么在本地准备好要么先不提。九、禁止 mention 与维护者审查节奏规范第八条要求不要mention贡献者和导师、不要催促 PR 审查。理由很直接通知堆积the pile of notifications不会让 issue 被更快看到反而增加维护者的通知负担。这与通用贡献文档中“不要请求维护者 triage 你的 issue也不要 mention 他们索取关注”完全一致——重要 issue 会由维护者按自身节奏处理。对 GSoC 学生而言正确的等待姿势是把审查等待时间投入到本地打磨补测试、补文档、截图、完善 PR 描述使 PR 自身达到“自包含”self-contained标准。十、禁止 force push保留增量审查能力规范第九条规定不要 force push修改 PR 时应以新增 commit 的方式推送这样维护者只需审查新增改动一旦 force push已审查的历史被改写维护者只能从头重新审查整个 PR。这条规则保护的是审查状态的可追溯性——在“一次机会”的前提下改写历史等于主动放弃已获得的审查进度。十一、提交前自检清单综合规范原文与仓库支撑一份合格的 Joplin GSoC PR 在提交前应通过以下检查检查项依据issue 已有 high/medium/enhancement 等 triage 标签且非本人/朋友创建规则 0、规则 1同一时间只有一个未合并的 PR规则 2PR 自包含地说明了功能、实现方式、用法示例与截图而非“Implement #xxxx”一句带过readme/dev/index.md 贡献指南借用代码已披露来源与自研边界规则 4已附带单元测试且yarn test或包内yarn test可运行通过无法单测时附手工测试计划规则 5、packages/lib/jest.config.js功能已完成且可用无 WIP 内容规则 6未 mention 任何维护者或导师、未催促审查规则 7历次修改均以新 commit 追加未使用 force push规则 8规范结尾亦保留了沟通出口如果规则中有任何不清楚之处或有疑问欢迎向维护者反馈。总体而言这套规则是“以限制换取公平与质量”的流程设计——对贡献者而言读懂每条规则的动机比记住规则本身更能保证在有限的 GSoC 评审窗口内交出可被合并的作品。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考