Mongoose 贡献指南从 Bug 报告到提交 Pull Request 的完整开发协作手册【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose本篇指南以 MongooseMongoDB 异步环境的对象建模库仓库根目录下的 CONTRIBUTING.md 为骨架结合仓库内真实的 npm 脚本、测试基础设施与代码风格配置系统讲解如何为 Mongoose 贡献代码如何写出可复现的 Bug 报告、如何提出有价值的 Feature 请求、如何遵循仓库编码规范提交代码、如何在本机完整运行测试套件、如何为文档与 TypeScript 类型定义做贡献以及如何参与周边生态与财务支持。读完本文你将掌握从发现问题到PR 被合入的完整协作流程并能在本地搭建与 CI 一致的开发环境。一、贡献前的定位提问与报告的区别Mongoose 社区把使用问题与Bug 报告严格区分使用问题非 Bug请发到 StackOverflow 的mongoose标签或 Gitter 社区讨论而不是提交 Issue。这样既能让更多社区成员参与解答也避免污染 Issue 跟踪器。Bug 报告确认是仓库自身缺陷后再按下面的规范提交 Issue。这条定位规则在仓库的 CONTRIBUTING.md 开头即被明确强调是参与贡献的第一步也是尊重维护者时间的基本礼仪。二、提交高质量 Bug 报告2.1 报告前的查重在新建 Issue 之前务必先检索既有 Issue避免重复。如果确实不存在同类问题再创建新 Issue。2.2 报告内容清单一份合格的 Bug 报告应当包含以下要素最小可复现代码优先提供一段独立可运行的脚本用代码展示问题而不是用文字描述问题原文明确强调Do not describe your issue in prose. Show your code.。完整堆栈跟踪如果错误伴随异常请附上 stack trace。版本信息注明使用的 Mongoose 版本与 MongoDB 版本这是复现问题、定位回归的关键参数。语言约束Bug 报告中的复现脚本必须使用可在原生 Node.js 中运行的 JavaScriptES5/ES6 皆可不要使用 CoffeeScript、TypeScript、JSX 等需要额外编译的语言——因为仓库本身的核心源码就是用原生 JavaScript 编写的见 lib 目录维护者需要在无编译环境下直接复现。三、请求新功能从 Use Case 到测试用例提出 Feature 请求时同样需要先查重然后描述一个具体的使用场景use case说明这个功能解决什么实际问题、在什么业务背景下需要它。尽可能附带测试用例有测试的提案比空泛的描述更容易被维护者评估和合入。功能请求与 Bug 报告共用同一套 Issue 流程但侧重点不同Bug 报告面向现状坏了Feature 请求面向未来需要什么。四、修复 Bug / 新增功能的开发规范4.1 动手前的检查开始写代码之前先浏览既有 Issue确认没有人在做同样的工作避免重复劳动确认该方向是维护者感兴趣、值得投入的有些工作可能已在其他分支处理完毕。4.2 分支与提交方式常规改动Fork 仓库后在自己的分支上开发。小型文档改动可以直接在 GitHub 源码页面点击 Edit 按钮在线修改无需本地 Fork。4.3 代码风格规范仓库强制执行Mongoose 的代码风格由 eslint.config.mjs 落地为 ESLint 规则npm run lint即可本地校验。规范要点如下规范项要求对应的 ESLint 规则缩进2 个空格2 space tabsindent: [error, 2, ...]行尾空白不允许尾随空白no-trailing-spaces: error条件语句空格关键字与括号间 1 个空格如if (..) {keyword-spacing函数括号函数名与参数括号间无空格如function(err) {space-before-function-paren: [error, never]注释新方法、类成员需带行内文档注释spaced-comment引号统一单引号quotes: [error, single]分号必须使用分号semi: error此外仓库还对for、while等控制结构保持一致的括号风格。从 eslint.config.mjs 可以看到除了上述规则还启用了no-throw-literal、no-const-assign、no-dupe-keys等防错规则并且对 Mocha 全局globals.mocha做了白名单配置测试文件里禁止出现.onlymocha-no-only/mocha-no-only: [error]防止.only被误提交导致 CI 只跑单测。4.4 测试要求必须通过功能测试测试放在 test 目录例如 test/model.test.js、test/schema.test.js修改源码时必须保证相关测试通过。TypeScript 类型测试如果修改了 TypeScript 类型定义types 目录下的.d.ts文件必须在 test/types 目录如 test/types/schema.test.ts补充类型测试。五、在本机运行测试套件5.1 安装依赖npm install仓库的 package.json 声明了运行时依赖mongodb、mquery、kareem、sift、mpath等与大量开发依赖mocha、eslint、typescript、tstyche、mongodb-memory-server等engines.node要求Node.js 20.19.0。5.2 启动 MongoDBnpm run mongo该命令通过 tools/repl.js 启动一个内存版 MongoDB ReplicaSet使用mongodb-memory-server监听端口27017副本集名称rs0默认2 个节点存储引擎wiredTiger通过--setParameter ttlMonitorSleepSecs1把 MongoDB 的 TTL 过期任务调度周期设为 1 秒用于加速 TTL 索引相关测试测试数据库名称为mongoose_test。如果你本机 27017 端口已经有一个 MongoDB 实例在运行可以跳过此步骤。若要指定 MongoDB 版本启动npm run mongo -- 4.2.2版本号会作为参数传入MongoMemoryReplSet的binary.version见 tools/repl.js由mongodb-memory-server自动下载对应版本的二进制。5.3 运行全部测试npm test实际执行的是mocha --exit --ignore test/encryption/**/*.test.js ./test/**/*.test.js见 package.json测试框架为Mocha。Mocha 的全局配置见 .mocharc.ymlreporter 为spec比默认的 dot 更适合识别失败/慢速用例UI 采用bdd预加载 test/mocha-fixtures.js仅扫描*.test.js扩展名。测试基座 test/mocha-fixtures.js 会在全局 Setup 阶段自动创建内存 MongoDB 实例单实例 可选副本集并通过MONGOOSE_TEST_URI/MONGOOSE_REPLSET_URI环境变量注入连接串如果设置了MONGOOSE_TEST_URI则直接使用既有实例而不启动内存库。CI 环境下还会设置MONGOMS_PREFER_GLOBAL_PATH1复用二进制缓存。测试连接封装在 test/common.js 中同样支持用MONGOOSE_TEST_URI覆盖连接地址。5.4 运行单个测试npm test -- -g some regexp that matches the test description-g后跟一个匹配测试描述describe/it字符串的正则表达式。所有 Mocha 参数都可以通过-- mocha flags here透传例如npm test -- -R spec使用specreporter默认输出是一串点号。5.5 运行 TypeScript 类型测试与基准npm run test:types类型测试由tstyche驱动tstyche.json 定义了匹配test/types/*.test.*与test/types/**/*.test.*的文件。另外还有两个 TypeScript 编译性能基准命令npm run ts-benchmark # 单次运行 npm run ts-benchmark:watch # 监听 types 目录变化持续运行执行前请先提交全部改动ts-benchmark在 benchmarks/typescript/simple 项目中安装依赖并跑 benchmark结果交给 scripts/tsc-diagnostics-check.js 做诊断检查。5.6 运行加密相关测试FLE对于需要加密集群的测试对应 test/encryption 目录例如 test/encryption/encryption.test.jsnpm run setup-test-encryption npm run test-encryption两条命令的语义如下setup-test-encryption执行 scripts/setup-encryption-tests.js下载 MongoDB8.0 Enterprise二进制与crypt_shared动态库用mongodb-runner启动一个 sharded 加密测试集群并把集群 URI 与 crypt shared 库路径写入fle-cluster-config.jsontest-encryption执行mocha --exit ./test/encryption/*.test.js单独跑加密测试普通npm test会忽略该目录。整个配置过程可能需要几分钟。另一种方式是使用 Shell 脚本 scripts/configure-cluster-with-encryption.sh它会拉取 MongoDB 官方驱动团队维护的drivers-evergreen-tools固定提交配置TOPOLOGYsharded_cluster、AUTHauth、SSLnossl等环境变量后启动分片集群。使用 FLE 功能的前提是具备mongocryptd或共享库以及 4.2 的 Enterprise 版 MongoDB 服务器。修改加密配置时官方推荐的步骤是编辑 scripts/configure-cluster-with-encryption.sh 中的环境变量重启 shell使新环境变量生效删除已存在的data/目录重新运行配置脚本。六、为文档做贡献Mongoose 的文档体系分为两部分贡献路径不同文档类型修改对象位置API 文档如api/mongoose.html源码内的行内 JSDoc 注释lib 目录对应源码文件指南 / 快速上手文档.pug/.md文件docs 目录如 docs/guide.md、docs/index.mdAPI 文档由源码注释自动生成因此改 API 文档就是在改源码注释指南类文档直接修改 Markdown/Pug 源文件即可。小型改动同样可以走 GitHub 的 Edit 按钮。6.1 本地预览文档先在本地 master 分支提交你的文档改动然后npm install npm run docs:viewdocs:view执行 scripts/static.js它会调用 scripts/website.js 完成资源拷贝与全站渲染website.copyAllRequiredFiles()website.renderAllFiles()启动静态文件监听website.startWatch()以便改动即时重编译最后在http://127.0.0.1:8089启动 Express 静态服务器端口可由PORT环境变量覆盖打开该地址即可预览本地文档。6.2 提交前的清理npm run docs:cleanPR 提交前必须执行清理docs:clean会删除构建产物index.html、docs/*.html、docs/api、docs/tutorials/*.html、docs/typescript/*.html、docs/source/_docs、tmp等见 package.json。因为自动化生成的docs/*文件不应出现在 PR 中只提交源文件。6.3 文档风格规范链接到 Mongoose 文档内其他文件时必须使用不带前缀的相对路径用guide.html而不是./guide.html或/docs/guide.html。这条规则保证了文档在任意部署路径下链接都有效。七、仓库周边的协作机会7.1 插件网站插件网站plugins.mongoosejs.io本身也是一个开源项目欢迎 Fork 并改进它。如果你想贡献一个 Mongoose 插件或优化插件展示页这里是切入点。7.2 财务贡献Mongoose 通过 Open Collective 接受透明的财务贡献任何人可以提交报销申请expense只要该支出对社区发展有意义核心维护者会将其合入mergedOpen Collective 账本并予以报销。贡献者Contributors与赞助者Backers都会在 Open Collective 的公开图表中署名致谢。八、贡献流程速查表阶段关键动作参考路径提问StackOverflow / Gitter而非 Issue—报告 Bug查重 → 最小可复现脚本 堆栈 版本CONTRIBUTING.md请求功能查重 → Use Case 测试用例CONTRIBUTING.md写代码Fork → 遵循 2 空格缩进等风格 →npm run linteslint.config.mjs写测试功能测试进 test类型测试进 test/typestest / test/types跑测试npm install→npm run mongo可选→npm testtools/repl.js / .mocharc.yml跑类型测试npm run test:typeststyche.json跑加密测试npm run setup-test-encryptionnpm run test-encryptionscripts/setup-encryption-tests.js改文档API 改 lib 注释指南改 docs 源文件docs/guide.md预览文档npm run docs:view→ http://127.0.0.1:8089scripts/static.js提交前清理npm run docs:cleanpackage.json遵循以上流程你的 Bug 报告将更容易被复现你的 PR 将更快通过 lint 与测试两道关卡。无论是修复一个 cast 错误、优化一个 Schema 选项还是补充一段中文指南文档这套协作规范都是进入 Mongoose 社区的第一张门票。【免费下载链接】mongooseMongoDB object modeling designed to work in an asynchronous environment.项目地址: https://gitcode.com/GitHub_Trending/mo/mongoose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考