深入 Noms 仓库:从环境搭建到代码提交与性能测试的完整贡献指南 数据库版本控制后端【免费下载链接】nomsThe versioned, forkable, syncable database项目地址https://gitcode.com/gh_mirrors/no/noms点击查看免费下载Noms 是一个版本化、可派生forkable、可同步syncable的数据库。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合仓库源码与测试完整讲解参与 Noms 开发的全流程从 Go 环境准备、Go Modules 构建、代码风格与错误处理约定到 PR 提交流程、常规测试与性能perf测试的实践方法帮助读者掌握一套可复现、可验证的贡献工作流。环境准备安装并验证 Go 工具链参与 Noms 开发的第一步是搭建 Go 环境。按 Go 官方安装文档完成安装后要求Go 版本至少为 1.11仓库的 go.mod 中声明的模块版本为go 1.12因此 1.12 及以上同样适用。安装完成后在终端验证版本# 必须至少是 1.11 go version确认输出形如go version go1.12.x linux/amd64且版本号不低于 1.11 即可继续后续步骤。获取并构建 NomsGo Modules 时代的检出与编译Noms 使用 Go 语言官方的Go Modules特性来管理依赖。这一点对既有 Go 用户尤为关键不要把仓库检出到$GOPATH目录内如果你确实只能在$GOPATH下操作可以设置环境变量GO111MODULESon强制启用模块模式。说明GO111MODULES这一名称在文档中沿用了 Go Modules 早期版本的习惯拼写其标准形式为GO111MODULE。在 Go 1.16 及更高版本中模块模式已是默认行为因此通常情况下只需确保检出目录在$GOPATH之外即可。构建与验证命令如下cd 任意非 $GOPATH 目录 git clone https://github.com/attic-labs/noms cd noms go install ./cmd/noms go test ./...其中go install ./cmd/noms编译并安装 Noms 的命令行主程序。cmd/noms目录下集中了noms.go、noms_blob.go、noms_map.go、noms_ds.go、noms_serve.go、noms_sync.go等一系列子命令的实现安装后即可获得noms可执行文件。go test ./...递归运行仓库内全部包的单元测试是验证环境与代码正确性的最快手段。许可证与贡献者协议Noms 是开源软件采用 Apache License, Version 2.0 许可仓库根目录的 LICENSE 文件即为该许可证全文共 201 行。出于法律原因所有贡献者在提交 PR 被接受之前必须签署贡献者协议Contributor Agreement——个人贡献者签署个人版协议公司/机构贡献者签署企业版协议。这是所有外部代码贡献进入仓库的前提条件。贡献代码语言、代码风格与提交规范允许的语言贡献代码时仅允许使用三种语言Go核心后端实现语言JS主要用于cmd/noms/sploreNoms 的可视化探索工具等前端部分其源码位于cmd/noms/splore/src下如main.js、layout.js、node.js等并通过webpack.config.js打包Python主要用于仓库工具脚本例如tools/noms下的copy.py、staging.py、symlink.py以及根目录的tools/licensify.py。Shell 脚本不被允许涉及自动化需求时应优先考虑用 Python 或 Go 实现。编码风格要求Go必须使用gofmt格式化建议在编辑器中接入 gofmt 的自动格式化钩子保证提交的 Go 代码风格统一JS遵循 Airbnb JavaScript Style GuidePR 标签提交 PR 时用toward: #bug或fixes: #bug标注该变更所关联的 issue 编号帮助维护者理解变更的上下文与动机Commit Message遵循 Chris Beams 的 commit message 风格指南核心要点包括主题行与正文用空行分隔、主题行不超过 50 个字符、以动词开头、正文解释“为什么”而非“是什么”。Go 错误处理约定d 包的异常式错误Noms 的错误处理采用两套并行的风格对外公开 APIPublic API默认使用 Go 惯例的返回值式错误即函数返回error由调用方处理非对外代码提供并鼓励使用基于panic/recover的异常式Exception-style错误包装工具。使用这种风格必须给出充分理由——典型场景是当前代码不知道该怎样继续执行而需要 panic但你希望向上层调用栈传递“可被 recover 并继续运行”的信号。为此仓库提供了go/d包见 go/d/try.go包含如下“抛出一个可捕获错误”的函数族函数语义d.PanicIfError(err)当err ! nil时将错误包装后 panic见 go/d/try.god.PanicIfTrue(b)当b true时 panic默认错误信息为Expected true见 go/d/try.god.PanicIfFalse(b)当b false时 panic默认错误信息为Expected false见 go/d/try.go这三者在 Noms 内部被广泛使用例如 go/datas/database_common.go 中就通过d.PanicIfError(err)处理数据库操作错误。其底层机制是这些函数调用d.Wrap(err)把普通error包装为带调用栈信息的wrappedError同时实现Error()与Cause()方法见 go/d/try.go随后可由d.Try()或d.TryCatch()在栈上游捕获Try(f, types...)执行f若捕获到WrappedError当types为空时直接返回该包装错误当types非空且原始错误类型匹配时返回cause否则重新 panic见 go/d/try.goTryCatch(f, catch)执行f捕获到包装错误后交给catch回调决定如何处理见 go/d/try.god.Unwrap(err)若err是WrappedError则返回其Cause()否则原样返回见 go/d/try.go。配套的单测位于 go/d/try_test.go覆盖了Try在未匹配类型时重新 panic、TryCatch对类型过滤、Unwrap语义、PanicIfTrue/PanicIfFalse的边界行为以及Wrap(nil)返回 nil 等关键路径。注意仓库中还存在以d.Chk开头的旧式断言函数d.Chk定义于 go/d/try.go本质是绑定到panicker的 testify assert 实例。维护者计划移除这些用法对应 issue #3258新代码不要使用d.Chk统一改用上述d.PanicIfError/d.PanicIfTrue/d.PanicIfFalse族。提交 PR基于 Chromium 风格的分支评审流程Noms 的代码评审协议源自 Chromium 团队的实践提交 PR 的完整步骤如下创建 fork将待修改的仓库 fork 到自己的账号下例如从https://github.com/attic-labs/nomsfork 出https://github.com/username/noms添加 remote将 fork 添加为本地仓库的 remotegit remote add username https://github.com/username/noms推送分支将改动提交到 fork 的某个分支并推送git push username branch发起 PR用刚推送的分支创建 PR——通常只需在浏览器中打开上游仓库主页GitHub 会识别新分支并自动提示创建 PR请求评审当你认为 PR 已准备好接受评审时在对应的 issue 中评论并请求 review。有时评审人不会主动 review因为他们不确定你是否认为 PR 已经就绪迭代修改通过 GitHub 常规 review 流程与评审人反复沟通修改合入评审人满意后由评审人负责合入submit变更。运行测试go test 与 Jenkins 集成常规单元测试go test是最直接的测试入口例如go test $(go list ./... | grep -v /vendor/)该命令会运行除 vendor 包之外的所有测试。仓库中的测试覆盖十分全面例如cmd/noms下每个子命令都有对应测试文件noms_blob_get_test.go、noms_commit_test.go、noms_diff_test.go、noms_ds_test.go、noms_log_test.go、noms_merge_test.go、noms_root_test.go、noms_show_test.go、noms_sync_test.go、noms_version_test.go等它们均基于 testify 的suite.Run组织测试套件。Jenkins 集成如果你或仓库具有提交权限commit rightsJenkins 会在每次 PR 及随后的每个补丁patch上自动运行 Go 测试。如需立即触发一次测试任何具备提交权限的人都可以在 PR 下回复不含引号Jenkins: test thisPerf 性能测试默认情况下go test和 Jenkins 都不会运行性能测试因为它们耗时较长。性能测试由 go/perf/suite 包驱动需要显式使用-perf与-v标志go test -v ./samples/go/csv/... -perf mem该命令以mem内存存储为后端数据库运行samples/go/csv目录下所有包的性能测试详细文档见 go/perf/suite 包注释。如何编写一个 perf 测试以仓库自带的 samples/go/csv/csv-import/perf_test.go 为例编写 perf 测试的基本模式为定义一个继承suite.PerfSuite的测试套件结构体type perfSuite struct { suite.PerfSuite csvImportExe string }在结构体上定义以Test开头可含前导数字用于手动排序的方法例如Test01ImportSfCrimeBlobFromTestdata、TestParseSfCrime调用suite.Run启动套件Run的第一个参数是结果数据集datasetIDfunc TestPerf(t *testing.T) { suite.Run(csv-import, t, perfSuite{}) }suite.Run的行为细节见 go/perf/suite/suite.go它会按-perf标志决定是否跳过测试测试名会去掉Test前缀与前导数字如Test01Import...记录为Import...每个测试的耗时被拆分为elapsed净执行时间、paused暂停时间可用PerfSuite.Pause(fn)排除长耗时的准备代码见 go/perf/suite/suite.go与total总时间测试结果连同环境信息CPU、内存、磁盘、主机信息见getEnvironmentgo/perf/suite/suite.go以及 noms 与 testdata 的 git revision 一起写入 Noms 数据库数据集。Perf 测试的完整参数go/perf/suite包注册了以下命令行标志定义于 go/perf/suite/suite.go标志类型默认值作用-perfstring指定写入性能测试结果的数据库。为空则跳过 perf 测试传mem可进行“干跑”dry run不落盘-perf.memboolfalse用内存存储chunks.MemoryStorage而非 NBS 磁盘存储作为底层 store会改变测试计时但在磁盘空间紧张时可用-perf.prefixstring结果数据集 ID 的前缀例如foo/会让结果写入foo/csv-import而非csv-import-perf.repeatint1每个 perf 测试重复执行的次数-perf.runstring仅运行与正则表达式匹配大小写不敏感的 perf 测试-perf.testdatastringtestdata 目录路径默认是$GOPATH/src/github.com/attic-labs/testdataPerfSuite还支持 testify 风格的 Setup/TearDown 生命周期钩子go/perf/suite/suite.goSetupSuite/TearDownSuite整个套件执行一次SetupRep/TearDownRep每次重复受-perf.repeat控制执行一次SetupTest/TearDownTest每个测试执行一次。运行结果示例go/perf/suite包注释给出了真实运行形态go/perf/suite/suite.gonoms serve go test -v ./samples/go/csv/... -perf http://localhost:8000 -perf.repeat 3输出形如(perf) RUN(1/3) Test01Qux (recorded as Qux) (perf) PASS: Test01Qux (5s, paused 15s, total 20s) (perf) RUN(1/3) Test02Bar (recorded as Bar) (perf) PASS: Test02Bar (15s, paused 2s, total 17s)随后用noms show查看写入数据库的结果结构noms show http://localhost:8000::csv-import结果中包含environment运行环境快照、tests每次重复的测试耗时映射含elapsed/paused/total三个纳秒级时长字段以及nomsRevision、testdataRevision等字段。在 CI 上跑 perf 测试如需让 Jenkins 代为运行 perf 测试在 PR 下回复不含引号Jenkins: perf this结果可在 Noms 的公开 perf 查看站点按pr_$your-pull-request-number/csv-import数据集查看。注意只有具有提交权限committer的人才能触发该操作。小结贡献 Noms 的完整检查清单Go 版本 ≥ 1.11仓库基于go 1.12模块且在非$GOPATH目录检出go install ./cmd/noms构建成功go test ./...通过已签署个人或企业贡献者协议Apache 2.0 许可下新代码仅使用 Go / JS / Python不使用 Shell 脚本Go 代码经gofmt格式化JS 遵循 Airbnb 风格PR 打上toward:/fixes:标签commit message 遵循 Chris Beams 指南公开 API 返回错误非公开代码如需异常式错误使用d.PanicIfError/d.PanicIfTrue/d.PanicIfFalse不要用将被废弃的d.Chk按 Chromium 风格流程提交 PR 并主动请求评审常规测试用go test性能测试用go test -v ./samples/go/csv/... -perf db并可借助 Jenkins 的Jenkins: test this/Jenkins: perf this触发远程测试。赞分享数据库版本控制后端【免费下载链接】nomsThe versioned, forkable, syncable database项目地址https://gitcode.com/gh_mirrors/no/noms点击查看免费下载相关推荐Redux Toolkit 仓库贡献指南从环境搭建、构建测试到提交 Pull Request 的完整工作流Redux Toolkit 仓库贡献指南从环境搭建、构建测试到提交 Pull Request 的完整工作流 本篇指南以仓库根目录的 CONTRIBUTING.前端状态管理BiliNote代码贡献指南从环境搭建到PR提交的完整流程BiliNote代码贡献指南从环境搭建到PR提交的完整流程 BiliNote是一个开源的AI视频笔记助手支持通过哔哩哔哩、YouTube、抖音等视频链接自AI 应用大模型RAG语音后端前端桌面应用为 nuqs 仓库贡献代码从 Worktree 开发环境搭建到测试、Lint 与合并的完整指南为 nuqs 仓库贡献代码从 Worktree 开发环境搭建到测试、Lint 与合并的完整指南 next usequerystate 包名为 nuqs 是前端状态管理上一篇探索复杂网络的利器igraph库下一篇推荐使用Wonder Shaper - 网络带宽智能管理工具创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考