p5.js 贡献者完整指南从提交 Issue 到合并 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.js本篇技术指南以 p5.js 官方贡献者指南contributor_docs/es/contributor_guidelines.md为骨架面向希望向 p5.js 提交代码的开发者系统讲解先 Issue、后 PR的协作全流程如何用四类 Issue 模板发起提案、如何搭建本地开发环境并遵守 Git 工作流、如何创建并完善 Pull Request、如何解决合并冲突。读完本文你将掌握一套可以在真实开源仓库中直接落地的参与流程并理解每一步背后的批准机制与代码质量约束。一、认识 p5.js 的 Issues 工作流1.1 什么是 GitHub Issues在 p5.js 的 GitHub 仓库中绝大多数开发讨论都发生在Issues问题中——这是新贡献者开始参与的最佳入口。一个 Issue 可以是一次错误报告、一个新功能请求、一场讨论或任何与 p5.js 库开发相关的话题。任何拥有 GitHub 账号的人都可以在 Issue 下方发表评论这使 Issue 成为社区围绕源码开发进行交流的主要场所。需要注意的是Issue 的用途是有边界的自己 sketch 代码的排错、邀请协作者加入你的项目等与 p5.js 源码开发无关的话题应当放到官方论坛或 Discord 等社区渠道讨论而不是开 Issue。p5.js 社区用一套模板来帮助贡献者判断该发 Issue 还是该发帖。1.2 p5.js 的 Issue 模板体系p5.js 在仓库的 .github/ISSUE_TEMPLATE/ 目录下维护了一套模板贡献者点击仓库顶部 Issues 标签页再点击右侧绿色 New Issue 按钮后即可看到模板选择页。选择最贴合你场景的模板能让 Issue 更快获得正确的关注。目前主要有四类模板适用场景前置批准要求Found a Bug报告错误p5.js 出现与文档不符的错误行为至少 1 位 Steward 批准Existing Feature Enhancement现有功能增强改进现有功能函数、常量、渲染等至少 1 位 Steward 批准Feature Request新功能请求为 p5.js 增加全新功能至少 2 位 Steward 批准Discussion讨论不属于上述三类、需要先收集社区意见的话题视讨论结果而定从仓库实际的模板文件如 .github/ISSUE_TEMPLATE/2-found-a-bug.yml可以看到模板由 YAML 定义的表单字段组成字段一旦填写就会自动为 Issue 打上对应标签。1.3 报告错误Found a Bug当你发现 p5.js 行为异常或与文档描述不符时使用该模板。如果你的问题其实是自己 sketch 代码的问题请先到论坛求助再考虑报 Bug。该模板要求填写以下关键信息最合适的子区域Most appropriate sub-area勾选受影响的模块如 Color、DOM、WebGL、Typography 等会自动添加对应的 标签帮助维护者快速定位。p5.js 版本查看 p5.js/p5.min.js 文件第一行的版本号构建时版本号会被写入文件头部 banner见 rolldown.config.js 的 banner 逻辑当前仓库版本为 2.3.1见 package.json。浏览器及版本不同浏览器行为差异很大按下表查询ChromeFirefoxSafari地址栏输入chrome://version地址栏输入about:support顶部菜单 Safari → 关于 Safari操作系统尽量带上版本号如macOS 12.5部分错误与操作系统行为相关。复现步骤Steps to reproduce这是最重要的信息。提供详细的分步复现清单并附上一段最小可复现代码片段能极大加速问题定位。复现是关键。模板的大部分字段都是为了帮助他人复现错误提供的信息越多社区越容易帮你找到解决方案。同时要避免笼统表述不要只说image()函数不工作而应具体到image()函数没有以正确的尺寸显示加载的 GIF 图片。一个实用的描述框架是同时说明期望行为代码应该做什么与实际行为代码实际做了什么。批准机制与先 Issue 后 PR铁律一个 Bug 报告要被接受并进入修复流程必须获得至少 1 位 区域 Steward 或维护者 的批准。在对应 Issue 被批准之前不要提交 Pull Request 或开始改代码——解决方案可能不被接受、可能需要完全不同的思路或者真正的问题在别处。任何未获批就提交的 PR 都会被关闭直到相关 Issue 获得批准。1.4 现有功能增强Existing Feature Enhancement如果你想改进 p5.js 中已存在的功能例如给color()函数增加新的颜色定义方式使用该模板。需要填写提高可访问性Increasing Access必填字段说明该改进如何帮助历史上在艺术与技术领域被边缘化的群体更好地使用 p5.js。没有这份声明提案不会被接受如果不确定可以填 No estoy seguro我不确定并开启对话由社区协助完善。最合适的子区域自动打标签便于分诊。改进细节一个好的提案通常包含具体用例——该功能是什么、何时需要、如何用、为什么需要。改进提案同样需要至少 1 位 Steward 批准且同样适用先 Issue 后 PR的规则。1.5 新功能请求Feature Request如果你要提议的是 p5.js 中全新加入的功能例如新增一个绘制 HTMLtable元素的createTable()函数使用该模板。若提案与既有改进重叠请自行判断选择更合适的模板。必填字段与增强模板一致可访问性声明、子区域、新功能细节但批准门槛更高至少 2 位 Steward 批准后才能开始实现。1.6 开启讨论Discussion当你的 Issue 不属于上述任何模板时这类情况相对少见可以使用讨论模板。例如p5.js 是否应该采用某项 Web API应当走新功能请求模板是否给颜色函数增加新模式应当走增强模板而本地编程活动公告则更适合发到论坛。讨论模板是一个开放字段你还可以从右侧的Labels面板添加标签来标记讨论类型。当讨论收敛并拆解出更具体的 Issue 后原讨论会被关闭。二、在 p5.js 代码库上工作2.1 前置要求开始之前你至少需要具备命令行与 git 的基本操作能力、Node.js18 或更高版本以及一个可用的本地开发环境。你可以用node -v确认 Node.js 是否已安装。2.2 快速开始Developer Quick Start当你的 Issue 已被讨论、实现方案获得批准后就可以动手了。完整步骤如下Fork p5.js 仓库到自己的 GitHub 账号。Clone 你的 fork 到本地。将本地仓库与官方上游仓库建立关联以便同步最新代码git remote add upstream 官方 p5.js 仓库地址确认 Node.js 已安装node -v安装全部依赖推荐npm ci按 lockfile 精确安装npm ci从main分支切出一个新分支分支名要能描述你的改动git checkout -b [branch_name]改代码期间高频运行测试防止破坏既有行为npm test若你实现的是新功能或改进同步补充单元测试。完成后提交commit改动并创建 Pull Request。注意排队规则如果某个 Issue 已经有人表明要贡献、或已被分配出去**不要插队**直接提交 PR——p5.js 会优先按分配顺序接受贡献在他人仍在处理同一 Issue 时提交的 PR 会被关闭。如果某 Issue 已数月无人活动可以礼貌留言询问进展或提供帮助。2.3 使用 GitHub 网页编辑功能在 GitHub 网页浏览文件时内容右上角有一个铅笔图标按钮可对文件做简单的在线编辑。但只建议用于非常简单的改动复杂的源码改动需要先本地编译、验证后再进 PR本地开发环境远比 GitHub 的基础网页编辑器流畅。2.4 Fork 并本地开发Fork 是在你的 GitHub 账号下创建仓库副本这是向官方仓库提交代码的前提通常你不会有官方仓库的直接写权限。点击仓库页面顶部的 Fork 按钮即可完成。使用 GitHub Desktop图形界面适合 git 新手下载安装 GitHub Desktop 并登录。在项目列表中选择你的 fork名为你的用户名/p5.js点击蓝色 Clone 按钮选择存放位置。克隆完成后选择To contribute to the parent project向原项目贡献并继续。使用命令行打开你的 fork 页面点击绿色 Code 按钮复制 git URL形如https://github.com/你的用户名/p5.js.git。在终端中克隆git clone [git_url]克隆耗时取决于网络速度。完成后打开p5.js文件夹即可开始探索源码。2.5 代码库结构剖析p5.js 仓库的关键目录如下src/—— 所有最终被合并为 p5.js / p5.min.js 的源码所在例如颜色模块见 src/color/核心渲染见 src/core/。test/—— 单元测试与文档示例测试代码详见 单元测试指南其中test/unit/的目录结构镜像src/的模块划分。contributor_docs/—— 贡献者文档本指南所在目录含 访问声明、Steward 指南 等。lib/—— 构建产物p5.js、p5.min.js 等输出目录。docs/、translations/、utils/—— 文档数据、多语言翻译、构建辅助脚本。其余文件多为配置或辅助文件多数情况下无需修改。需要特别说明的是原指南中提到的tasks/目录在 p5.js 2.0 中已被移除——从当前仓库结构看构建逻辑由根目录的 rolldown.config.js 与 package.json 中的 npm scripts 承担。2.6 构建配置一切开始之前先安装依赖。确认 Node.js 已安装后执行npm cinpm 会下载全部依赖可能需要一些时间完成即配置完毕。从 package.json 可以看到当前项目的核心脚本npm run build—— 使用 Rolldown 构建rolldown -cnpm test—— 使用 Vitest 运行测试vitestnpm run lint—— 代码风格检查当前为oxlint .npm run docs—— 生成 API 文档数据npm run bench—— 运行基准测试构建输出由 rolldown.config.js 定义src/app.js会被打包为lib/p5.jsIIFE 格式、lib/p5.min.js压缩版、lib/p5.esm.js与lib/p5.esm.min.jsESM 格式WebGPU 附加模块会输出为lib/p5.webgpu.js系列文件同时src/下每个文件会被单独输出为 ESM 到dist/目录。2.7 Git 工作流切入正题前先跑一遍测试确认基线是干净的npm test该命令会从零编译 p5.js 并运行全部单元测试应当无错误通过。若只想构建而不跑测试npm run build两个命令都会把库构建到lib/目录p5.js与p5.min.js你可以直接用这些产物做自己的验证。分支策略强烈建议在main之外单独开分支。分支是仓库的独立版本线你可以在上面提交 commit 而不影响main或其他分支即使改错了也不会波及主干。GitHub Desktop 中点击顶部 Current Branch 输入新名称创建终端中在main分支上执行git checkout -b branch_name。提交频率尽量高频、小步提交而不是把一大堆改动塞进一个 commit。一个实用的准则是每完成一个能用一句话描述的子任务就提交一次。终端提交流程检查只列出了你改动的文件git status如果列出了你未改动的文件要么用git restore还原要么确认这些改动是有意为之。要看每个文件的详细变更用git diff不要提交任何与本次 PR 无关的文件改动。暂存全部改动git add .提交并写清消息git commit -m [your_commit_message]提交信息要具体避免笼统描述。例如与其写Documentation fix 1不如写git commit -m Add documentation example to circle() function整个开发过程中请定期运行npm test并在每次提交前确保测试通过。2.8 不同工作类型的子指南源码Código fuente如果你清楚自己要改哪个功能最佳起点是 p5.js 在线参考文档——每个已文档化功能页面的底部都有指向其源码文件的链接例如src/shape/2d_primitives.js点击即可直达实现文件。单元测试Pruebas unitarias详见 单元测试指南。功能增强、新功能以及部分 Bug 修复必须在 PR 中附带覆盖新实现的单元测试。在线文档Documentación en línea详见 贡献 p5.js 参考文档。可访问性Accesibilidad详见 Web 可访问性友好错误系统Friendly Error System相关贡献见 friendly_error_system.md。2.9 代码标准p5.js 使用代码风格检查原指南基于 ESLint当前仓库 package.json 中 lint 脚本为oxlint .约束提交质量。任何 commit 和 PR 都必须通过风格检查才会被接受。最省力的方式是给编辑器安装对应的 lint 扩展在编码时实时看到风格错误。2.10 软件设计原则在 p5.js 上工作请务必理解它与多数项目不同的设计优先级完整表述见 设计原则文档亦可参考 访问声明可访问性优先Acceso所有决策都要考虑如何扩大对历史上被边缘化群体的访问。对新手友好Amigable para principiantesAPI 面向编程初学者用简单方式封装 HTML5/Canvas/DOM 的高级能力。教育性Educativo以支持教学为目标提供完整 API 参考、示例、教程与课程大纲。JavaScript 及其社区用规范且恰当的 JavaScript 模式向初学者示范 Web 开发实践同时保持开源、欢迎更广泛的 JS 社区参与共建。Processing 及其社区p5.js 源自 Processing 语言目标是让从 Processing(Java) 迁移到 JavaScript 的过程顺畅清晰。三、Pull Requests当你完成改动含必要的单元测试、npm test无报错、且已 commit 后就可以准备 Pull RequestPR了。PR 本质上是向官方仓库p5.js发起提取并合并你 fork 仓库中提交历史的请求。3.1 创建 Pull Request第一步是把新 commit 推送到你的 forkGitHub Desktop点击顶部右侧的推送按钮publish/push把分支推送到 GitHub。终端git push -u origin [branch_name]推送完成后终端可能直接给出打开 PR 的链接也可以在浏览器中进入你的 fork用顶部下拉切换到目标分支点击 Contribute → Open pull request访问 p5.js 官方仓库时若检测到新推送也会显示 Compare pull request 按钮。3.2 填写 PR 模板提交 PR 前需要完整填写 PR 模板见 .github/PULL_REQUEST_TEMPLATE.md。p5.js 的 PR 模板包含以下部分标题Titulo简要概括改动内容同样避免笼统描述。Resolves解决模板中有Resolves #[填写 issue 编号]一行将其中的编号替换为你要解决/处理的 Issue 编号如Resolves #1234。这样 PR 合并后对应 Issue 会自动关闭。如果你不希望自动关闭该 Issue例如还有后续改动在另一个 PR 中把Resolves改为Addresses解决中/涉及。Changes变更清晰描述本次改动包括与审查者相关的实现细节和决策。Screenshot截图可选但当改动涉及 p5.js 在 canvas 上的视觉渲染时应当提供。注意这里指的是示例 sketch 运行效果的截图而不是文本编辑器的截图。Checklist检查清单将[ ]改为[x]勾选与你的改动对应的条目。完成后点击 Create pull request。3.3 检查已打开的 PR打开 PR 后检查以下几点Commits 数量应与你的实际提交数一致做了 2 个 commit 就应只显示 2 个。Files changed 标签页应只包含你相对官方仓库做的改动不多不少。页面底部应显示This branch has no conflicts with the base branch而不是存在冲突的提示。若以上任一不成立commit 过多或存在冲突则可能需要 rebase 或解决冲突。冲突意味着你改过的文件近期也被他人改动git 无法确定保留哪组变更。3.4 解决合并冲突在网页上解决GitHub 有时会直接显示 Resolve conflicts 按钮。冲突代码位于与标记之间中间以分隔一侧是你的代码、另一侧是主干上的新改动。删除冲突标记、只保留最终想要的代码然后点击 Mark as resolved全部解决后提交合并即可。在本地解决当冲突过于复杂、或你更习惯手动处理时# 1. 添加上游仓库若尚未添加 git remote add upstream 官方 p5.js 仓库地址 # 2. 拉取上游最新提交 git fetch upstream # 3. 基于上游 main 变基 git rebase upstream/main此时可能产生冲突。如果冲突只涉及lib/p5.js和lib/p5.min.js很好办——重新构建项目即可npm run build。如果冲突在其他文件且不知如何解决请向维护者求助。随后npm test git add -u git rebase --continue最后推送git push补充提示在 p5.js 2.0 中npm test由 Vitest 驱动会启动浏览器环境执行单元测试与视觉测试具体项目配置见 vitest.config.js含unit-tests与unit-tests-webgpu两个测试项目基于 Chromium。测试目录结构可参考 test/unit/events/keyboard.js 等文件模块加载清单见 test/unit/spec.js。3.5 讨论与修正PR 提交后会有一位 Steward 或维护者来审查响应可能需要几天时间请耐心等待。审查结果有两种① PR 被批准并合并② 审查者提出疑问或要求修改。后者完全正常——Steward 会协助你完成贡献。如果需要修改沿用之前的 Git 工作流在本地对应分支上继续改代码、commit、推送到远程 fork。推送新 commit 后它们会自动出现在 PR 中。在 PR 中留言告知审查者已完成修改若无进一步要求你的 PR 就会被合并四、附标签体系与审批规则速览为帮助你在提交前判断 Issue 归属这里整理 p5.js 的标签体系详见 issue_labels.md状态标签Bug、Discussion、Enhancement、Feature Request、Help Wanted、Good First Issue推荐给首次贡献者、More Info Needed等。区域标签Area:Accessibility、Area:Color、Area:Core、Area:Data、Area:DOM、Area:Events、Area:Image、Area:IO、Area:Math、Area:Typography、Area:Utilities、Area:WebGL等与src/目录结构一一对应。专项标签Build Process、Unit Testing、Internationalization、Friendly Errors、Documentation。审批门槛汇总Bug 修复与功能增强需1 位 Steward批准新功能请求需2 位 Steward批准新功能/增强类 PR 需2 位 Steward审查通过后方可合并。所有规则都服务于同一目标让每一次贡献都经过充分讨论、可复现、可测试并始终把可访问性放在第一位。【免费下载链接】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），仅供参考