p5.js 贡献者入门指南从开发环境搭建到提交第一个 Pull Request【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.jsp5.js 是一个面向艺术家、设计师与编程学习者的客户端 JavaScript 创意编程框架。本文基于仓库内 contributor_docs/ja/README.md 贡献入门文档系统梳理 p5.js 的贡献方式、仓库文件结构、GitHub Issue 协作流程以及完整的本地开发闭环环境搭建、构建、代码风格检查与单元测试。读完本文你将掌握为 p5.js 提交代码或文档贡献的完整路径并能对照当前仓库的实际工具链rolldown 构建、Vitest 测试、oxlint 静态检查正确执行每一步操作。一、p5.js 的贡献生态不止于写代码p5.js 是一个由众多志愿者协作的开源项目社区欢迎各种形式的参与撰写参考文档、教学、编程、创作艺术作品、写作、设计、活动组织、展览策划等。官方 贡献者指南 明确指出项目遵循 all-contributors 规范贡献者的名字与贡献类型会被记录在贡献者列表中。从代码角度贡献通常分为两类源码贡献含文档遵循标准的 Issue → 讨论 → 批准 → 编码 → PR → 评审 → 合并 流程详见 contributor_guidelines.md非源码贡献如示例、教程、社区活动等。对于新手一个很好的切入点是修复参考文档中的错误或不完善之处——参考文档被认为是该项目最重要的部分之一也是新用户与新贡献者面临的最大障碍。二、p5.js 相关代码仓库全景p5.js 项目并不只有一个代码仓库围绕核心库还分布着多个配套仓库仓库职责p5.js本仓库核心源码用户使用的参考文档也由源码内的 JSDoc 注释生成p5.js-website官方网站大部分代码参考文档除外p5.js-soundp5.sound 声音扩展库对应本仓库 lib/addons/p5.sound.jsp5.js-web-editor网页版编辑器p5.accessibility面向盲人与视障用户的辅助功能库需要说明的是旧版的 p5.js-editor 已不再维护新贡献应面向 web-editor 仓库。三、仓库文件结构导览贡献文档建议不必一开始就理解所有文件可以先从某个具体区域例如几处参考文档修正入手再逐步探索。以下是原文档描述并结合当前仓库实际核对后的结构总览contributor_docs/贡献者应当遵守的各类指南包括 unit_testing.md单元测试、contributing_to_the_p5js_reference.md参考文档贡献、friendly_error_system.md友好错误系统等docs/不包含参考文档本身而是用于生成在线参考文档的代码与主题资源如 docs/yuidoc-p5-themelib/空示例lib/empty-example与 p5.sound 扩展库src/全部源码按模块组织如core/、color/、shape/、webgl/、webgpu/、friendly_errors/等修改 p5.js 行为时应主要关注这里多数子目录内有自己的 READMEtest/单元测试与视觉测试保证库在变更后依然行为一致utils/辅助脚本如类型生成、补丁工具通常可忽略顶层配置文件package.json脚本与依赖、rolldown.config.js构建配置、vitest.config.js测试配置、eslint.config.mjs与.oxlintrc.json静态检查配置。注意原贡献文档中提到的tasks/与tests/目录在当前仓库中已分别演进为package.json内的 npm scripts rolldown.config.js以及test/目录阅读旧文档时需以当前仓库实际结构为准。四、参考文档最容易被忽视的重要贡献入口p5.js 官方在线参考文档由src/中源码附带的 JSDoc 注释生成文本说明、参数描述与代码示例全部与源码放在一起这一设计强化了文档贡献与代码贡献同等重要的理念。构建库时会同步检查内联参考与示例是否与代码实际行为一致。想要贡献参考文档应先阅读 contributing_to_the_p5js_reference.md 与 jsdoc.md它们详细说明了 JSDoc 注释的写法、参数类型标注与示例代码规范。此外documentation_style_guide.md 提供了统一的文档风格约束method.example.js 则是一个可参考的注释模板。五、GitHub Issue 协作流程p5.js 使用 GitHub Issue 追踪已知 bug 与预期新功能并借助标签分类如level:beginner标记适合新手的问题标签体系见 archive/issue_labels.md。核心流程如下认领任务若想处理某个既有 Issue先在该 Issue 下评论让其他贡献者知道该问题已有人认领提交 PR完成相关工作后向 main 分支提交 Pull Request。PR 描述中必须包含关联标签若 PR 能完全解决该 Issue写resolves #XXXX若 PR仅部分处理合并后 Issue 仍需保持打开写addresses #XXXX先建 Issue 再提 PR发现 bug 或有新功能想法时应先提交 Issue 讨论获得维护者反馈与同意后再实现并提交 PR而不是直接提交包含修复或新功能的 PR——这能避免花费时间做可能不被接受的工作参与 Issue 分类包括复现 bug 报告、向报告者索要版本号与复现步骤等关键信息。关于 Issue 的组织方式与项目决策流程的高层概览可参考维护者视角的 steward_guidelines.md。六、开发环境搭建与本地构建p5.js 的开发流程对初学者可能略显复杂但按以下步骤可以顺利完成本地配置。遇到问题时可以在社区论坛讨论或提交 Issue 求助。1. 安装 Node.js 与 npm下载 node.js 安装包即可npm 包管理器会随之自动安装。2. Fork 并克隆仓库先将仓库 fork 到自己的 GitHub 账户再克隆到本地$ git clone https://gitcode.com/GitHub_Trending/p5/p5.js.git3. 安装依赖进入项目目录后使用 npm 安装全部依赖$ cd p5.js $ npm cinpm ci会严格按照 package-lock.json 安装所有依赖包括测试所需的框架。4. 构建库文件原贡献文档使用 Grunt 从源码构建库文件npm run grunt。当前仓库已迁移构建工具链查看 package.json 中的 scripts构建命令为$ npm run build底层由 rolldown.config.js 配置的 rolldown 完成产物输出到dist/与lib/。如果频繁修改库文件可以运行开发模式让源码文件每次变更时自动重建无需手动输入命令$ npm run devdev:global脚本还会同时启动预览服务器preview/便于在浏览器中即时验证全局模式下的改动。5. 提交本地修改修改源码后用 Git 提交$ git add -u $ git commit -m YOUR COMMIT MESSAGE提交前应再次运行构建与测试确认没有语法错误、测试失败等问题然后推送到自己的 fork$ git push一切就绪后即可通过 Pull Request 提交给上游仓库。七、代码风格与静态检查p5.js 的开发工具在某种意义上被刻意设计得相当严格——这能保持代码一致性并激励开发者写出风格统一的代码。即使经验丰富的 p5.js 开发者也会偶犯同样错误常见问题通常只有两类代码语法或单元测试。1. 运行 lint 检查原文档推荐 ESLintnpm run lint/npm run lint:fix当前仓库已改用 oxlint但 npm 脚本名保持一致查看 package.json 可确认$ npm run lint部分语法错误可以自动修复$ npm run lint:fix完整的规则配置见 eslint.config.mjs 与.oxlintrc.json。以当前配置为例可以从中看到 p5.js 核心风格规则的落地形式单引号优先stylistic/quotes: [warn, single, { avoidEscape: true }]见 eslint.config.mjs缩进使用 2 个空格stylistic/indent: [warn, 2, ...]见 eslint.config.mjs强制分号、禁用尾随逗号、行尾统一为 unix 风格等。2. 核心代码风格要点原贡献文档总结了以下代码风格规则完整列表仍以配置文件为准使用 ES6 语法p5.js 语言层面已迁移至 ES6影响说明见 archive/es6-adoption.md优先使用单引号缩进使用 2 个空格所有变量至少被使用一次否则彻底删除不要写x true或x false改用(x)或!(x)容易产生歧义时对象与null比较、字符串与比较、数值与0比较在复杂或语义含糊处写注释。项目整体对代码风格保持灵活性目标是降低参与门槛。虽然保持既有风格通常是可取的但偶尔也有使用// prettier-ignore注释允许个别例外的情况——尽量少用因为 lint 强制的大多数格式规则背后都有其合理性。八、单元测试保证 p5.js 行为一致性单元测试是大型代码库保持低 bug 率的关键它是一小段用于验证某个组件函数、变量、类行为正确性的代码。p5.js 用它确保新改动不引入回归regression。详细指南见 unit_testing.md。1. 测试工具链当前仓库原贡献文档描述的工具链是 Mocha mocha-chrome Grunt$ grunt浏览器打开test/test.html。当前仓库已迁移至 Vitest通过 vitest.config.js 配置Vitest作为测试运行器提供 Mocha 兼容的全局 APIsuite、test、setup、teardown等Chai作为断言库由 Vitest 内置打包也可直接从 Vitest 导入import { assert, expect } from vitest;运行全部测试$ npm test由于 p5.js 测试用例数量庞大npm test通常耗时较长不必每次改动都全量运行。测试在真实浏览器Chromium由 Playwright 驱动中执行并同时提供两个浏览器窗口一个渲染并执行所有单元与视觉测试、可交互筛选结果另一个是 Vitest 与浏览器通信的 DevTools 通道可忽略。2. 测试文件组织test/目录下所有测试相关文件都集中在test/unit/子目录其子目录结构与src/的源码模块一一对应。例如 test/unit/events/keyboard.js 对应 src/events/keyboard.js而 src/color/p5.Color.js 的测试则位于 test/unit/color/p5.Color.js。目标是让 p5.js 的每个公开函数都有对应的单元测试。3. 编写单元测试的完整范例以p5.prototype.keyIsPressed为例其期望行为是有任意键按下时为true无键按下时为false。可据此设计测试用例该变量是布尔值按下键时为true按下任意键字母、数字、特殊键时均为true同时按下多个键时为true无键按下时为false。在实际测试文件中suite()描述被测单元每个test()是检查该单元单一行为的测试用例。文件顶部通过setup/beforeAll创建实例模式instance mode的 sketch并将p参数赋给myp5从而在任意测试中访问 p5.js 的变量与函数let myp5; setup(function (done) { new p5(function (p) { p.setup function () { myp5 p; done(); }; }); });然后使用 Chai 断言编写具体测试test/unit/events/keyboard.js 中有真实可运行的实现suite(p5.prototype.keyIsPressed, function () { test(keyIsPressed should be a boolean, function () { assert.isBoolean(myp5.keyIsPressed); }); test(keyIsPressed should be true on key press, function () { window.dispatchEvent(new KeyboardEvent(keydown)); assert.strictEqual(myp5.keyIsPressed, true); }); test(keyIsPressed should be false on key up, function () { window.dispatchEvent(new KeyboardEvent(keyup)); assert.strictEqual(myp5.keyIsPressed, false); }); });注意这里通过window.dispatchEvent(new KeyboardEvent(keydown))模拟真实按键事件来驱动被测行为。断言函数在条件为false时抛出错误其行为类似if判断完整的断言函数清单可查阅 Chai 的 assert API 文档。4. 新增测试文件的步骤若为src/下新增的源文件添加对应测试复制一个现有测试文件并重命名以匹配源文件名删除旧测试代码保留 setup 与 teardownsuite(module_name, function () { let myp5; let myID myCanvasID; setup(function (done) { new p5(function (p) { p.setup function () { let cnv p.createCanvas(100, 100); cnv.id(myID); myp5 p; done(); }; }); }); teardown(function () { myp5.remove(); }); });将新增模块注册到 test/unit/spec.js 的spec对象中确保测试运行时加载所需模块// test/unit/spec.js var spec { // ... typography: [attributes, loadFont, p5.Font, yourModule] // ... };在 suite 内添加实际测试suite(module_name, function () { // ... setup / teardown ... suite(p5.prototype.yourFunction, function () { test(should [test something], function () { // Your test code and Chai assertions }); }); });5. 测试约定每个被测函数/变量使用一个suite其中可包含任意数量的test每个test应当自包含不依赖 p5.js 的其他模块测试代码尽可能精简一次只测一件事——不要在同一个test中既测值的类型又测参数接收应拆分为两个test优先使用 Chai 的assert而非expect可用.skip跳过某 suite、用.only只运行某 suite// 该 suite 不会运行 suite.skip(p5.prototype.yourFunction, function () {}); // 只运行该 suite忽略其他所有 suite suite.only(p5.prototype.yourFunction, function () {});单元测试还承担着回归防护的职责src/中的源码若发生重大变更或新增功能test/中应当有配套测试验证该行为在库的未来所有版本中保持一致。未通过测试的 PR 意味着代码中存在错误不应提交。九、视觉测试捕捉渲染层面的回归除单元测试外p5.js 2.0 还通过视觉测试确保 sketch 的渲染结果不因实现变更而意外改变。视觉测试文件位于test/unit/visual/cases/目录无需手动注册Vitest 会自动发现每个文件内包含多个用例每个用例创建示例 sketch 后调用screenshot()与基准截图对比核心实现见 test/unit/visual/visualTest.js。一个典型的视觉测试用例visualTest(2D objects maintain correct size, function (p5, screenshot) { p5.createCanvas(50, 50, p5.WEBGL); p5.noStroke(); p5.fill(red); p5.rectMode(p5.CENTER); p5.rect(0, 0, p5.width / 2, p5.height / 2); screenshot(); });运行npm test时尚无基准截图的视觉测试会自动生成新截图存入test/unit/visual/screenshots/下次运行即以此作为对比基准。若某个测试有意需要改变外观可删除screenshots/中对应测试名的文件夹后重跑重新生成基准。p5.js 2.0 的视觉测试系统使用更稳健的 diff 算法来区分可接受的平台差异与真实 bug。不同操作系统与浏览器在渲染上存在细微差异如线条的单像素偏移、抗锯齿差异、文本渲染差异、曲线平滑度差异这些差异不应导致测试失败。算法要点初始对比使用中等阈值0.5配合 pixelmatch 库逐像素比较用广度优先搜索BFS将相连的差异像素聚类识别线条偏移簇可能是同一视觉元素整体位移 1px与孤立的噪点像素智能失败标准忽略小于 4 像素的簇、允许最多 40 个显著差异像素、容忍跨平台的轻微线条偏移const MIN_CLUSTER_SIZE 4; // 最小显著簇大小 const MAX_TOTAL_DIFF_PIXELS 40; // 允许的最大显著差异像素数若簇内超过 80% 的像素邻居数 ≤ 2则判定为线条偏移而非结构性差异。这一机制让测试套件既能捕捉真实渲染 bug又显著减少了因平台渲染差异导致的误报。视觉测试最佳实践画布尽量小优先使用接近 50×50 像素的尺寸对比前测试系统会为性能缩小图片小画布在 CI 上更快聚焦可见细节小尺寸下细节难以分辨测试 sketch 应使用缩小时仍清晰可见的元素来演示被测特性一个测试多次截图不要把所有变体塞进一张截图多次调用screenshot()visualTest(stroke weight variations, function (p5, screenshot) { p5.createCanvas(50, 50); // 细线条 p5.background(200); p5.stroke(0); p5.strokeWeight(1); p5.line(10, 25, 40, 25); screenshot(); // 细线截图 // 粗线条 p5.background(200); p5.strokeWeight(5); p5.line(10, 25, 40, 25); screenshot(); // 粗线截图 });涉及异步操作如 3D 模型加载时返回一个在测试完成后 resolve 的 Promise确保运行器等待异步操作结束visualSuite(3D Model rendering, function () { visualTest(OBJ model is displayed correctly, function (p5, screenshot) { return new Promise(resolve { p5.createCanvas(50, 50, p5.WEBGL); p5.loadModel(unit/assets/teapot.obj, model { p5.background(200); p5.rotateX(10 * 0.01); p5.rotateY(10 * 0.01); p5.model(model); screenshot(); resolve(); }); }); }); });CI 环境中优化测试速度同样重要保持代码精简、避免多余帧、最小化画布尺寸仅在测试特定功能确有必要时加载资源。下图分别展示了 p5.js 测试在浏览器界面与终端中的运行效果十、提交 Pull Request 前的最终检查清单综合原贡献文档与当前仓库工具链一次完整的贡献提交流程如下在相关 Issue 下评论认领任务本地搭建环境npm ci并完成代码修改运行npm run lint检查语法与风格必要时用npm run lint:fix自动修复为新功能/变更补充单元测试必要时补充视觉测试并运行npm test确认全部通过运行npm run build或npm run dev的自动重建确认库可正常构建提交git add -ugit commit并推送git push到自己的 fork向 main 分支发起 Pull Request在描述中按约定填写resolves #XXXX或addresses #XXXX。即使提交被项目拒绝也不必气馁——经验丰富的 p5.js 开发者也会犯同样的错误。问题通常集中在代码语法或单元测试两类参照 contributor_guidelines.md 与 unit_testing.md 修正后重新提交即可。十一、其他有用的资源contributor_docs/目录下的其余文档覆盖了项目技术与非技术层面的各个领域例如 friendly_error_system.md友好错误系统、webgl_mode_architecture.mdWebGL 架构、webgpu.mdWebGPU 支持等构建过程会生成包含 p5.js 公开 API 的 JSON 数据文件可被自动化工具如编辑器中的语法自动补全使用社区论坛与 Issue 是获取帮助的主要渠道维护者steward会在能力范围内提供支持相关信息见 steward_guidelines.md。p5.js 将贡献视为一次学习机会不以贡献数量衡量成功也没有完成贡献的时间限制。放慢节奏、按自己的速度推进遇到问题随时求助这是项目最鼓励的参与方式。【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考