参与 Johnny-Five 开源贡献指南:从提 Issue 到提交 PR 的完整工作流

发布时间:2026/9/23 2:32:26

参与 Johnny-Five 开源贡献指南:从提 Issue 到提交 PR 的完整工作流 IoT机器人嵌入式【免费下载链接】johnny-fiveJavaScript Robotics and IoT programming framework, developed at Bocoup.项目地址https://gitcode.com/gh_mirrors/jo/johnny-five点击查看免费下载导读CONTRIBUTING.md 是 Johnny-FiveJavaScript 机器人与物联网编程框架官方维护的贡献规范文档。本文以此文档为核心系统拆解贡献者应遵循的完整工作流——包括如何报告 Issue、请求新功能与新硬件支持、提交 Pull Request、编写单元测试、维护文档示例并结合仓库中真实的 Gruntfile.js、package.json、test/common/bootstrap.js 与 tpl/programs.json 等源码佐证帮助你在动手之前理解项目方代码必须通过测试与规范校验、硬件功能必须附带文档的硬性验收标准从而一次通过审查。Johnny-Five 是一个开源、基于 Firmata 协议的物联网与机器人编程框架支持 Arduino全系列、Intel Edison、Raspberry Pi、Particle/Spark、Tessel 2 等大量平台详见 README.md。它由 Nodebots 社区维护代码质量门槛较高所有贡献代码必须通过 lint、代码风格检查与单元测试涉及新硬件的功能还要求附带接线图与可运行示例。下面按贡献路径逐一展开。贡献途径总览根据 CONTRIBUTING.md 的 Guideline Contents任何人均可通过以下七种途径参与报告 IssueReporting an Issue请求新功能Requesting Features请求新硬件支持Hardware Support提交 Pull RequestSubmitting Pull Requests编写测试Writing Tests编写文档Writing Documentation提交示例项目Sample Projects报告 Issue信息完备是排查硬件问题的前提硬件项目的 bug 排查极度依赖现场信息。文档要求报告者在提交 Issue 前先在仓库的 Issue 中搜索确认该问题是否已被报告过若已存在但你有新的排查线索则在原线程中以评论方式补充以下同样格式的信息。新建 Issue 时必须包含的字段如下字段说明与示例Board开发板型号如 Arduino Uno、Intel Edison 等Shield若使用了扩展板注明类型Hardware you are having an issue with出问题的硬件及其品牌/型号例如 servo、led、sensorVersion of Johnny-FiveJohnny-Five 版本号What your expectations are你期望的行为What the actual outcome is实际发生的行为Steps to reproduce (including code samples)复现步骤必须附带代码示例此外文档特别建议如果可能附上一段演示视频可上传至任意支持视频托管的平台这在实际调试硬件问题时往往极为有效。从仓库实现看Issue 模板要求附带代码示例是有充分理由的——Johnny-Five 的程序必须先等board触发ready事件才能操作引脚见 eg/board.js 中board.on(ready, ...)的写法。大量所谓硬件不工作的 Issue 实际是初始化时序或引脚编号问题一份可复现的最小代码能让维护者快速定位是硬件、固件还是库本身的问题。请求功能与硬件支持请求新功能若希望为现有类class增加功能创建一个 Issue 并说明What feature youd like to see希望看到的功能Why this is important to you为什么这对你很重要了解社区成员正在做什么有趣的事也便于其他成员在功能未实现前给出 work-around 建议请求新硬件支持社区维护者可能并不拥有你手中的新硬件因此请求支持时必须创建 Issue附带该硬件的规格说明书链接与购买渠道若你已拥有该产品通常会被建议由你自己协助实现支持。仓库中可观察到硬件支持的实际形态每个硬件控制器都有对应的lib/实现与test/测试例如 test/led.js、test/accelerometer.js并在 tpl/programs.json 中登记对应示例条目docs/下则有按硬件型号命名的文档如 docs/led-PCA9685.md。这说明硬件支持不是一句承诺而是一整套可运行的代码、测试与文档交付物。提交 Pull Request代码、测试、文档三者缺一不可分支与准备流程将项目 fork 到自己的 GitHub 账号在独立分支中完成工作提交 PR 前将 master 变基rebase进你的分支确保包含最新改动、不产生冲突使用 grunt 进行lint 与测试将提交squash 压缩到合理数量后再提交。代码风格规范所有贡献代码必须遵循Idiomatic.js Style Guide并保持与现有代码一致的风格。仓库中的实际规范配置可从以下文件确认.jshintrc启用esversion: 9、强制curly、eqeqeq、双引号quotmark: double、检测未使用变量unused: true等.jscsrc配合grunt-jscs使用的代码风格规则。硬性验收标准文档强调两条不可妥协的红线贡献代码必须附带单元测试测试在缺少该功能代码时失败、加入实现后通过提交 PR 前必须运行grunt jsbeautifier修复语法格式问题。从 Gruntfile.js 可以确认默认任务链grunt.registerTask(default, [jshint, jscs, nodeunit]);即一次grunt会依次执行 JSHint 语法检查、JSCS 风格检查与 nodeunit 单元测试任何一环失败即视为整体失败。devDependencies 中对应配置了grunt-contrib-jshint、grunt-jscs、grunt-jsbeautifier、grunt-contrib-nodeunit、sinon、mock-firmata等见 package.json。新硬件功能的文档要求当贡献的是支持新硬件的新功能时PR 必须包含Fritzing 接线图面包板接线图eg/目录中的带注释示例脚本wiki 中的 API 文档文档明确指出未附带文档的代码 PR 将不被接受Pull requests with undocumented code will not be accepted。仓库中docs/breadboard/下有大量.png.fzz成对出现的接线图资源即为该要求的落地产物。常用开发命令速查结合 Gruntfile.js 与 package.json贡献者常用命令如下命令作用grunt/npm test默认任务jshint jscs nodeunit 全套检查grunt jsbeautifier修复代码格式问题grunt qc仅运行 JSHint 与 JSCS 检查可指定文件如grunt qc:eg/led.jsgrunt nodeunit:file:file.ext运行指定测试文件grunt examples由eg/示例重新生成docs/对应文档并更新 READMEgrunt example:file-name在eg/下生成一个新的示例程序骨架grunt test-examples运行 examples 任务并检查docs/是否有未提交改动grunt watch监听文件变更并自动运行默认任务编写测试nodeunit sinon mock-firmata 的组合测试框架与技术栈文档明确说明测试使用nodeunit与sinon编写。仓库 test/common/bootstrap.js 展示了完整的测试引导方式引入全局EventEmitter、Collection、Emitter、Withinable、five即 lib/johnny-five.js等引入第三方库color-convert、serialport、firmata、temporal引入测试依赖mock-firmataglobal.mocks、global.MockFirmata、global.MockSerialPort使测试无需真实硬件即可在模拟 Firmata 设备上运行通过newBoard()辅助函数创建Board实例并触发connect/ready事件。以 test/led.js 为例可见典型测试结构setUp中创建newBoard()、建立 sinon sandbox、用 fake timers 与 spy 拦截digitalWrite/pinMode调用再断言 Led 的原型方法与实例属性on、off、toggle、blink、id、pin、value等是否符合预期。这正是文档所要求的缺少实现则测试失败、实现存在则测试通过的验证思路。extended 测试目录的特殊地位文档特别指出涉及时间要素的测试例如动画 animation、音调/歌曲 tone/song在部分硬件上可能不稳定容易导致 Travis CI 构建失败这类测试应放入test/extended目录。仓库中 test/extended/README.md 对此做了印证该目录下的测试存在长时间运行或在慢速硬件上失败的风险不随默认测试命令运行。而 Gruntfile.js 提供了独立任务grunt.registerTask(nodeunit:extended, () { grunt.config(nodeunit.tests, [ test/extended/animation.js, test/extended/led.js, test/extended/piezo.js, test/extended/servo.js, ]); grunt.task.run(nodeunit); });test/extended/目前包含 animation.js、led.js、piezo.js、servo.js 四个文件。需要运行完整测试含扩展测试时使用grunt nodeunit:extended。另外默认的nodeunit任务会先加载test/common/bootstrap.js再加载test/*.js下的全部测试见 Gruntfile.js。仅想写测试练手如果你对项目还不太熟悉可以关注 Issue 中带Tests标签的任务专挑写测试来加深对项目的理解。编写文档docs 与 eg 的自动生成联动机制文档维护是 Johnny-Five 贡献体系中自动化程度最高的一环理解其机制可避免大量无效劳动示例的唯一事实来源是eg/目录eg/中的每个示例文件都是用户可直接node eg/file运行的完整脚本docs/下的文档由eg/自动生成修改eg/中的示例后运行grunt examples会依据 tpl/programs.json 的条目自动重写docs/name.md与 README 中的示例索引提交时二者必须一起提交Gruntfile.js 中的grunt test-examples任务专门检查——若docs/有未提交的生成改动构建会直接失败提示 The generated examples dont match the committed examples. Please ensure youve run grunt examples before committing.新增文档需登记若新增了一个文档/示例文件必须将其加入tpl/programs.json否则不会出现在生成流程中。markdown注释块示例内嵌文档grunt examples的生成逻辑还支持一种注释即文档的写法。看 eg/led.jsled.blink(); }); /* markdown This script will make led available in the REPL, by default on pin 13. Now you can try, e.g.: js led.stop() // to stop blinking then led.off() // to shut it off (stop doesnt mean off) then led.on() // to turn on, but not blinkmarkdown */从 [Gruntfile.js](https://link.gitcode.com/i/34d2401c68527b6592c8d1bd0ca9b9d7#L264-L284) 的实现可以看到生成文档时markdown 标记之间的注释行会被提取出来作为 markdown 正文而脚本本体中的 ../lib/ 与 .js 后缀会被替换模拟 npm 安装后的 require(johnny-five) 写法。也就是说**为示例写文档只需在脚本注释里写清楚运行 grunt examples 即可产出正式文档**。 ### 文档写作的受众原则 文档应包含**经过测试且可运行的示例代码**、Fritzing 接线图、照片与视频适用时。由于 Johnny-Five 的许多用户是第一次接触硬件编程文档写作应以**初学者**为目标受众措辞和步骤要足够平易。 ## 示例项目让作品被更多人看到 如果你用 Johnny-Five 做出了有趣的作品欢迎让社区知晓——项目希望建立一个优秀项目目录帮助那些正在做类似项目的开发者寻找灵感、帮助与代码。可通过文档中提及的渠道例如 Issue 或社区讨论区提交你的作品信息。 ## 附本地开发环境速览 仓库根目录下还提供了若干配套资源贡献时可作为参考 - [lib/johnny-five.js](https://link.gitcode.com/i/bd03e1eadef1903adac1033ca2aed3e2)框架主入口package.json 的 main 字段 - [lib/](https://link.gitcode.com/i/ec20a832a658252258839edcb8700667)各模块实现如 [lib/led/](https://link.gitcode.com/i/a67b91e9b2c002685d6b51447c123d1f)、[lib/mixins/](https://link.gitcode.com/i/629f987bc0f1911b461eaf355498b228)、[lib/board.js](https://link.gitcode.com/i/9def10235e370aacc8744c47a6344cd4) 等 - [docs/](https://link.gitcode.com/i/39b1f5cb08ef040bda93d0f660dfbd1f)按硬件/功能主题组织的文档与 eg/ 示例一一对应 - [firmwares/](https://link.gitcode.com/i/115c535b5dfcb5267cee9911dcef6329)部分硬件如 I2C 背板所需的 Arduino 固件.ino - [assets/](https://link.gitcode.com/i/fe841e3dd52271760e6baf6269f42280)Logo 与示例动图等素材 - [appveyor.yml](https://link.gitcode.com/i/cda7ccd2ceb6e36dd0509bb9bcebd12f) 与 [package.json](https://link.gitcode.com/i/ad8612be921249b1a8606b91fd259967) 中的 CI 配置展示自动化检查的范围。 提醒Johnny-Five 与 Node REPL 不兼容——直接 node 进入交互式 REPL 运行会崩溃见 [README.md](https://link.gitcode.com/i/9d3afadd33ec36e38f89401640c5beed) 的说明。请将脚本写入文件后执行board 实例自身会创建其上下文 REPL。 ## 小结一次合规贡献的检查清单 结合本文全部内容向 Johnny-Five 提交代码前请逐项自检 1. 已 rebase 到最新 master无冲突 2. gruntjshint jscs nodeunit全部通过代码风格符合 Idiomatic.js 3. 已运行 grunt jsbeautifier 4. 新增/修改的功能有配套单元测试且测试在无实现时失败、有实现时通过 5. 涉及时间要素的测试放入 [test/extended/](https://link.gitcode.com/i/5a098d567a3cba0215e19f42987a2217) 6. 新硬件功能附带 Fritzing 接线图、eg/ 带注释示例、API 文档 7. 修改示例后运行 grunt examples 重新生成 docs/并将二者一起提交新文件已在 [tpl/programs.json](https://link.gitcode.com/i/207fb3cb37f7f20a837212fa7acbfe21) 登记 8. 提交已 squash 为合理数量。 遵循这套流程你的贡献就能顺畅通过 CI 与维护者审查真正帮助到全球的 NodeBots 开发者。赞分享IoT机器人嵌入式【免费下载链接】johnny-fiveJavaScript Robotics and IoT programming framework, developed at Bocoup.项目地址https://gitcode.com/gh_mirrors/jo/johnny-five点击查看免费下载相关推荐kotlinx.coroutines 贡献指南从 Issue 提交到 PR 合入的完整工作流kotlinx.coroutines 贡献指南从 Issue 提交到 PR 合入的完整工作流 本篇指南面向希望在 kotlinx.coroutines 仓库中异步编程并发编程FreshRSS 贡献指南从提 Issue 到提交 PR 的 GitHub 开发工作流FreshRSS 贡献指南从提 Issue 到提交 PR 的 GitHub 开发工作流 本文面向希望参与 FreshRSS 开发的贡献者完整讲解官方推荐的问后端前端CLITrianglify开源贡献者指南从提交issue到PR的完整流程Trianglify开源贡献者指南从提交issue到PR的完整流程 你是否在使用Trianglify时遇到过bug却不知如何反馈或者有了新功能想法却不知从何图形学创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/23 2:27:26

前端模块化开发:从CommonJS到ESM的演进与实践

1. 从"面条式代码"到模块化:前端开发的进化之路十年前我刚入行前端时,接手过一个遗留项目——一个5万行代码的jQuery应用,所有功能都堆在三个巨型JS文件里。每次修改功能都像在拆炸弹,生怕引发连锁反应。这正是模块化要…

2026/9/23 2:27:26

基于Python Flask/Django的儿童安全教育平台开发实践

1. 项目背景与核心价值儿童安全教育一直是社会关注的重点话题。随着移动互联网的普及,传统的安全教育方式已经无法满足当代家庭的需求。这个项目正是基于Python Flask/Django框架与微信小程序生态,构建了一个专门针对儿童安全教育的知识科普平台。我最初…

2026/9/23 2:27:26

2026最新xlsx手机版面试突击:3个高频坑点与标准答法

2026最新xlsx手机版面试突击:3个高频坑点与标准答法 别再去啃那厚达几百页的Excel官方文档了,抓不住重点只会让你更焦虑。 很多开发者和测试同学以为,处理数据只是后端的事,前端和移动端完全可以无视文件格式。 但现实是,…

2026/9/23 3:22:29

华硕笔记本ATK驱动全解析:Fn键失灵、键盘灯不亮的排查与安装指南

如果手里有一台华硕或ROG笔记本,键盘背光灯突然不亮、Fn组合键完全没反应、调节音量时屏幕上那个小悬浮窗消失,大概率不是硬件坏了,而是ATK驱动这一整套底层组件没装对、没装全,或者被系统升级给顶掉了一部分。这篇内容不打算讲那…

2026/9/23 3:22:29

HIS系统对接医保五期接口:核心业务流程与联调排错实践

简介:上海五期医保接口说明是面向HIS系统开发商及医保接口对接工程师的技术文档,用于指导上海医保第五代接口的设计、开发与审核。文档从引言、业务分析到接口描述逐层展开,既解释卡类型、账户标志、费用结算单元、就诊单元号等核心名词&…

2026/9/23 3:22:29

Docker部署Redis 7全攻略:从环境准备到生产实践

在项目里折腾过好几次 Redis 部署之后,我现在的习惯基本就是一句话:能用 docker 部署 redis 7,就绝不在服务器上裸装。原因很简单,容器把 Redis 的版本、配置、数据目录全部固化下来,换机器、升级、回滚都变成了一条命…

2026/9/22 10:02:42

GAMP 5 基于风险的计算机化系统验证:软件分类与审计追踪实践

简介:《A Risk-Based Approach to Compliant GxP Computerized Systems》即业内熟知的GAMP 5指南,面向制药企业质量与IT合规人员、验证工程师及计算机化系统管理者,用于解决GxP法规环境下系统合规性难以科学落地的问题。文档以风险管理为主线…

2026/9/22 9:07:39

安全托管MSSP实战:从静态防御到人机协同的攻防运营与应急响应

简介:这份PPT围绕互联网业务安全托管服务展开,面向企业安全负责人、IT运维人员及关注MSSP/MSS选型的读者,重点回应传统安全过度依赖人工、碎片化静态防御难以对抗产业化攻击等痛点。资源共1个pptx文件,包体约30.63MB,以…

2026/9/23 0:01:54

3个实战技巧搞定形式英语:从看教程到跑通性能优化

3个实战技巧搞定形式英语:从看教程到跑通性能优化 看了一堆教程还是不会写项目?别慌,这种“眼高手低”的困境在开发者圈子里太常见了。很多人以为卡点在语法,其实真正拦路虎是缺乏将知识点串联成完整链路的能力。今天咱们不聊虚的,直接拿【形式英语】这…

2026/9/22 16:34:32

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/22 20:01:30

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/22 13:25:41

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码