Joplin GSoC 2023 Pull Request 规范：一份面向贡献者的提交守则与测试落地指南

Joplin GSoC 2023 Pull Request 规范一份面向贡献者的提交守则与测试落地指南【免费下载链接】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 2023 Pull Request 规范 逐条解读该年度提交规则的设计意图与执行边界并结合仓库根目录的 贡献文档、package.json 与各包的 Jest 配置说明规则 5“所有 PR 必须附带单元测试”在 Joplin 代码库中如何实际落地。读完本篇你可以掌握 Joplin 在 GSoC 期间筛选 Issue、撰写合格 PR 的完整流程以及如何按仓库既有测试体系编写和运行单元测试。背景为什么 Joplin 要对 GSoC 的 PR 设置限制Joplin 的 Google Summer of Code 计划面向移动端iOS/Android改进、插件与外部应用等方向2023 年是该项目连续参与的第三轮见 GSoC 2023 主页 与 想法清单。维护者在 PR 规范文档 开头说明由于资源有限为了保证每位参与者都有机会提交 Pull Request当年引入了明确的限制性规则。这套规则的共同逻辑是压缩无效审查成本把维护者精力集中在可合并、可验证的改动上。因此下文每条规则都可以理解为对“什么样的 PR 值得被认真审查”的一次界定。规则 08 全部继承自原文档下面按主题分组展开。选题规则只处理已被分诊triaged的 Issue规则 0原则上只处理已被管理员分诊过的 Issue——即带有high、medium或enhancement等标签的 Issue。这些标签意味着管理员已经审视过该问题并将其纳入待办backlog。原文档同时给出四个具体的选题方向修复 Bug最推荐从带high或medium优先级标签的 Bug 列表中挑选。Bug 修复“始终受欢迎”是最安全的切入点Good first issue挑选标记为good first issue的 Issue 作为入门功能请求 backlog查看带enhancement标签的待办功能请求。原文特别提示其中一部分较复杂、不适合第一次提交 PR但另一些比较简单可以优先考虑在自己的仓库实现插件可以为自己 fork 的插件仓库开发 Joplin 插件。注意维护者会审查你的代码所以选题“不要太 trivial过于简单”要能真正展示你的技术能力并且需要到官方论坛的插件类别中公告该插件。规则 1不得处理由你自己或你的朋友创建的 Issue——这类 Issue 很可能会被直接关闭。这两条合起来的含义是选题的合法性不取决于“问题是否存在”而取决于“问题是否经过社区共识流程被接受”。这与仓库根目录 贡献指南 中“贡献范围Contribution scope”一节的要求一致PR 应解决一个“具体的、已被达成共识的问题”并遵循“发现问题 → 讨论并被维护者接受 → Issue 被分诊打标签→ PR 针对已商定的方案实现”这一流程未遵循该流程的 PR 可能被关闭而不做详细评审。提交节奏规则一次一个 PR、禁止 WIP规则 2每位贡献者同一时间只能有一个进行中的 Pull Request。当前 PR 合并之后才能提交第二个。理由有二一是维护者资源有限若人人都能并行提交多个 PR 将无法认真审查二是这对你自己也有利——你只需专注于一个 PR就有时间把它做到尽可能好确保功能工作正常、附带单元测试、包含文档、以及如适用截图。规则 3如果 PR 存在严重问题、或需要大规模重写significant rewrite才可能达到可接受水平维护者可能会关闭它且你将不被允许再开一个新的 PR。因此原文用加粗强调发布 PR 前务必三思。规则 6不接受 Work In Progress进行中状态的 PR。只有“已完成且可正常工作、并带有单元测试”的 PR 才会被接受WIP PR 会直接落入规则 3 的情形——立即关闭。这三条规则构成了一条递进的“失败代价”链规则 6 保证你提交的是成品规则 3 保证提交失误的代价很高规则 2 保证在有限的提交机会内你把每个 PR 打磨到位。对贡献者的实际建议是在本地把功能、测试、文档都做完并自测通过后再创建 PR而不是“先开一个占坑 PR 再慢慢补”。诚信与协作规则代码来源披露、不催促、不 force push规则 4如果你借用了代码必须披露。原文说明借用代码本身是可以的有时甚至是被推荐的但维护者需要知道这一点才能正确评估你的工作。披露的典型形式是在 PR 描述中注明代码来源原 Issue 讨论、Stack Overflow、其他开源项目等。规则 7不要mention贡献者和导师也不要主动请求 PR 审查。审查排队有时需要时间但mention只会增加维护者收到的通知量并不会让你的 Issue 被更快处理。这一条与 贡献指南 中“不要要求维护者分诊你的 Issue也不要 mention 他们以获取关注”的要求完全呼应。规则 8不要 force push强制推送。当你对 PR 做修改时直接追加一个新的 commit 即可——这样维护者只需要审查新增的改动而一旦 force push所有历史被改写维护者只能从头重新审查全部内容。这条规则在 git 层面的含义是GSoC 期间的 PR 分支应保持提交历史线性追加append-only。相应的本地工作习惯是在功能分支上继续git commit后正常git push避免使用git commit --amendgit push -f这类改写历史的组合。规则 5 的落地Joplin 的单元测试体系与运行方式规则 5 是全部规则中最具体、也最容易被验证的一条所有 Pull Request 必须附带单元测试。原文承认在个别场景下加测试几乎不可能例如某些集成测试但对其他所有情形都会坚持如果发现“本可以加测试却没加”PR 可能被关闭。若你不知道如何写测试原文建议到论坛或 Discord 提问若确实无法添加测试维护者会在审查中告知。原文并指向 贡献指南中的 Automated Tests 一节 获取更多信息。下面结合仓库实际配置把这一要求展开为可操作的内容。测试框架与目录约定Joplin 使用Jest作为统一测试框架见 readme/dev/index.md 的 “Automated tests” 一节。新增测试文件的约定是在与被测源码相同目录下创建以.test.ts结尾的文件。例如为example.ts编写测试就创建example.test.ts若该文件已存在直接把新用例加进去。仓库采用 Yarn Workspaces 组织多包结构根 package.json 中workspaces: [packages/*]Jest 配置也是两层继承根目录的 jest.config.base.js 是所有子包 Jest 配置的基座当前只设置了一项watchman: false禁用 watchman 文件监听各包配置都从它展开以核心库 packages/lib/jest.config.js 为例它展开基座配置后补充了testMatch: [**/*.test.js]、testEnvironment: node、setupFilesAfterEnv加载jest-expect-message与本包的jest.setup.js、slowTestThreshold: 40超过 40 秒的用例会被标记为慢测试。值得注意的是该配置在非 CI 环境下会跳过 OneNote 导入相关测试因为本地开发者不要求安装 Rust 工具链在 CI 环境中则执行。如何运行测试根据 贡献指南 与 根 package.json 的test脚本yarn workspaces foreach --worktree --parallel --verbose --interlaced --jobs 2 run test在仓库根目录执行yarn test即可并行触发所有工作区包的测试。也可以进入具体包目录运行例如在packages/lib下执行yarn test该包的test脚本就是jest。针对单个文件或单个用例# 运行 markdownUtils.test.ts 中的全部测试 yarn test markdownUtils # 只运行其中描述为 should handle conflict 的那条测试 yarn test markdownUtils --filtershould handle conflict带数据库与同步器的测试如何搭建对于涉及数据库、同步等重依赖的逻辑仓库在 packages/lib/testing/test-utils.ts 中提供了成套工具函数例如setupDatabaseAndSynchronizer、createNTestNotes、expectThrow、switchClient、db等。packages/lib/models/Note.test.ts 是一个典型的参照其开头直接从../testing/test-utils导入createNTestNotes、setupDatabaseAndSynchronizer、expectThrow、db、encryptionService、revisionService等工具从而在内存数据库中搭建完整的“模型 同步器”测试环境。贡献指南也明确建议若测试需要数据库或同步器支持参考该文件即可而纯粹的简单函数测试则不需要这些额外搭建。此外针对 React Hooks 的测试建议使用testing-library/react-hooks包贡献指南中给出了桌面端ResizableLayout相关 hook 测试文件作为示例。确实无法加单测时手动测试计划Manual Testing Plan贡献指南在 “If it is not possible to add tests” 一节给出降级方案这部分正是 GSoC 规则 5 中“若确实不能加测试维护者会告知你”这一句对应的操作标准先把代码重构一遍看能否把依赖较多的逻辑拆成无依赖的简单函数——简单函数天然易于单测若单测仍不充分必须提供手动测试计划包含至少 5 个测试步骤覆盖边界输入列表为 0/1/10/100000 个元素、空字符串、超长字符串等而不只是最佳情形一条以及如何验证相关模块没有被破坏例如改了笔记加载逻辑后检查工具栏行为、笔记切换、笔记列表标题是否仍正确标准是审查者拿到你的改动后可以按这份步骤独立复现验证。提交前自检清单把九条规则与仓库测试体系合并可以整理为一份提交前的自检流程选题Issue 是否带有high/medium/enhancement等分诊标签是否是自己或朋友创建的规则 0、1排他当前是否没有其他进行中的 PR规则 2完成度功能是否完整可用、无 WIP 遗留规则 6可审查性PR 描述是否自包含地说明了功能、实现方式、示例与截图借用的代码是否已披露规则 4另见 贡献指南 的 “Contribution guidelines”测试是否按.test.ts约定新增/补充了测试并用yarn test pattern本地跑通无法单测时是否写足了手动测试计划规则 5协作礼仪分支历史是否线性追加、未 force pushPR 中是否避免了mention催审规则 7、8风险评估这个 PR 是否可能被要求“大规模重写”若不确定先按 GSoC 2023 主页 的指引在论坛与导师沟通再提交。规则 3小结这份 2023 年的 PR 规范 本质是一份“提交资格 质量门槛”的双重契约选题门槛只接分诊 Issue、不自开自答保证维护者审查的是社区认可的问题提交门槛单 PR 制、禁 WIP、必须单测、禁 force push、来源披露保证每一个进入审查队列的 PR 都是完整、可验证、可增量审查的。对贡献者而言理解这些规则背后的审查成本约束比逐字背诵规则更重要——它解释了为什么 Joplin 宁可关闭 PR 也不做半成品合并以及为什么“写好测试、写好 PR 描述”本身就是 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），仅供参考