参与 Go Micro 开发从开发环境搭建到插件提交的完整贡献指南【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro本文以 Go Microgo-micro.dev/v6的官方贡献指南为主线系统讲解这个 A Go agent harness and service framework 项目的开发者协作流程从本地环境搭建、Makefile 工具链、Conventional Commits 提交规范到测试要求、插件目录结构与文档站点维护直至 Pull Request 提交与评审、问题报告和发布流程。读完本文你将能够按项目自身的门禁标准绿色 CI、一个 PR 一个关注点完成一次合规的代码、插件或文档贡献。说明文档站点下的 internal/website/content/en/docs/project/contributing.md 是仓库根目录 CONTRIBUTING.md 的渲染副本供网站读者便捷访问本文以两者为骨架并结合仓库源码与配置逐项展开。项目定位与贡献总览Go Micro 是一个面向微服务与 Agent 的开发框架它以 Go 接口构建可插拔架构定义服务发现registry、客户端/服务端 RPC、发布订阅broker等分布式系统基础能力并包含 auth、缓存、存储等原语最终封装在高层的 service 接口中见 internal/website/content/en/docs/project/_index.md。项目欢迎所有类型的贡献代码、文档、示例与插件plugins。无论你是修复一个 bug、为一个接口新增 registry/broker 实现还是改进站点文档都遵循同一套流程与质量门禁。快速开始五分钟跑通开发环境官方 Quick Start 给出了最小可用路径git clone https://gitcode.com/gh_mirrors/go/go-micro cd go-micro go mod download go test ./...Go 版本前提仓库 go.mod 声明module go-micro.dev/v6、go 1.25.0工具链为go1.25.12。贡献者本地 Go 版本应不低于模块声明版本。go mod download拉取全部依赖NATS、etcd、Consul、Postgres 驱动、gRPC 等之后即可跑通全量单测。开发工具链与 Makefile 目标仓库根目录的 Makefile 集中封装了开发期全部常用操作官方推荐直接使用这些目标而非裸命令# 安装开发工具golangci-lint、goimports、richgo、protoc-gen-micro make install-tools # 运行测试 make test # 竞态检测 覆盖率 make test-coverage # 运行 linter make lint # 格式化代码 make fmtmake help会打印全部可用目标。除上述基础目标外Makefile 还提供若干与项目特性Agent/Flow/CLI强相关的验证目标例如目标作用对应 Makefile 实现make test-racego test -v -race ./...全量竞态检测make harness运行确定性端到端契约CLI 寻路、inner-loop、0→hero transcript、agent-flow harness、mock provider 一致性测试无需任何 API keymake provider-conformance-mock用确定性 mock provider 跑跨厂商 agent/tool 语义一致性契约make provider-conformance对每个已配置的 live provider 跑同一套 harness未配置 key 的厂商自动跳过make proto用protoc --micro_out. --go_out.重新生成 protobuf 代码make install-smoke验证本地 install.sh 与首次运行的 CLI smoke 路径make clean清理 coverage 产物、测试二进制与 go 缓存这些 harness 目标直接对应 CI 的默认门禁路径官方建议在提交 PR 前本地跑一遍make harness把脚手架、run/chat/inspect、0→hero 回归问题拦截在提交之前。贡献流程与分支规范标准流程分四步Fork 仓库并创建功能分支做出聚焦的变更并附带测试运行 lint 与完整测试套件打开 PR说明动机与实现方式官方 Getting Started 给出了更细的分支操作# Fork 后克隆你自己的副本 git clone https://github.com/YOUR_USERNAME/go-micro.git cd go-micro # 添加 upstream 远端 git remote add upstream https://github.com/micro/go-micro.git # 创建功能分支一个分支只做一个功能/修复 git checkout -b feature/my-feature两条贯穿始终的硬性约束一个 PR 只解决一个关注点one feature/fix per PR保持小且可回滚先同步再提交PR 前执行git fetch upstream git rebase upstream/master确保分支基于最新 master。对自动化协作场景仓库根目录的 AGENTS.md 还规定Codex 任务的 PR 分支必须以codex/为前缀如codex/3012-fix-nats-leak由gh pr create亲自打开 PR 并启用gh pr merge --squash --auto --delete-branch由 CI 绿后 GitHub 原生 auto-merge 落盘。提交信息规范Conventional Commits所有提交使用 Conventional Commits 格式type(scope): subject body footer类型type与语义类型含义feat新功能fixBug 修复docs文档变更test测试新增/修改refactor代码重构perf性能优化chore维护性任务官方示例feat(registry): add kubernetes registry plugin fix(broker): resolve nats connection leak docs(examples): add streaming examplescope 建议使用受影响的接口/子系统名registry、broker、client、server、store、examples…便于快速检索与生成 CHANGELOG。测试要求与常用命令贡献代码必须携带测试。官方要求所有新代码都要有单元测试既有测试必须保持通过插件实现需要集成测试建议在多个 Go 版本下验证当前 go.mod 声明 Go 1.25。常用命令# 全量单元测试 go test ./... # 竞态检测与覆盖率 go test -race -coverprofilecoverage.out ./... # 只跑某个接口包 go test ./registry/... # 详细输出 go test -v ./... # 只跑某个测试函数 go test -run TestMyFunction ./pkg/... # 可选richgo 彩色输出 go install github.com/kyoh86/richgolatest richgo test -v ./...注意make test-coverage即go test -v -race -coverprofilecoverage.out -covermodeatomic ./...会同时输出coverage.html便于人工审查。此外涉及 Agent/CLI 行为变更时应关注 cmd/micro 下的契约测试与 internal/harness 中的确定性 harness它们是这类功能的事实标准。添加插件接口目录、结构与示例插件机制是 Go Micro 可插拔架构的核心。官方对新增插件的 6 项要求放在对应接口目录下如registry/myplugin/完整实现该接口包含全面的测试提供使用示例文档化配置项环境变量、options更新插件文档。推荐的目录结构registry/myplugin/ ├── myplugin.go # 主要实现 ├── myplugin_test.go # 测试 ├── options.go # 插件专属 options └── README.md # 用法与配置说明从源码结构看常见接口与现有实现的位置为详见 internal/website/content/en/docs/plugins.mdRegistryregistry/ 下consul、etcd、nats、mdnsBrokerbroker/ 下nats、rabbitmq、http、memoryTransporttransport/ 下nats默认httpServer/Clientserver/、client/ 下grpc原生 gRPC 兼容Storestore/ 下postgres、mysql、nats-js-kv、memory。插件通过直接导入子包并以 options 注入服务来使用例如注册 Consul registryimport ( go-micro.dev/v6 go-micro.dev/v6/registry/consul ) func main() { reg : consul.NewConsulRegistry() svc : micro.NewService(plugin-example, micro.Registry(reg)) svc.Init() svc.Run() }NATS broker、gRPC server/client、Postgres store 等均遵循同一模式micro.Broker、micro.Server、micro.Store…。要点是只导入你需要的插件保持二进制体积与依赖面可控不设置实现时框架使用内存/本地默认mDNS registry、HTTP transport、memory broker/store。文档贡献Hugo 站点与示例文档贡献与代码贡献同等重要。站点文档位于 internal/website/content/en/docs/站点本身由Hugo Docsy构建见 internal/website/README.md。官方要求涉及功能变更时更新internal/website/content/en/docs/下对应 Markdown新功能在 internal/website/content/en/docs/examples/ 增加示例重大特性同步更新仓库根 README.md为导出的函数/类型补充 godoc 注释。本地预览站点需要Hugo Extended、Go、Node.js# 在 internal/website 目录下 npm ci npm run serve生产构建GitHub Pages 使用npm ci hugo --gc --minifyDocsy 以 Hugo module 方式固定版本无需 submodule 检出。新增页面直接在internal/website/content/en/docs/下新建 Markdown 并提交 PR 即可。提交 Pull Request 与评审完整 PR 流程对应官方 Pull Request Process同步分支git fetch upstream git rebase upstream/master本地验证go test ./...与golangci-lint run推送git push origin feature/my-feature创建 PR描述性标题、关联相关 issue、说明改动内容与原因、UI 变更附截图、WIP 标记为 draft评审迭代及时响应反馈、按要求修改、更新后重新请求 review。提交前的 PR 检查清单本地测试通过代码遵循 Go 约定gofmt / golint文档已更新提交信息清晰分支已与 master 同步无合并冲突问题报告与社区提交 issue 前先做三件事搜索既有 issue、查阅文档、尝试最新版本。报告 bug 时使用 bug 模板并附带最小复现代码、版本信息Go 版本、Go Micro 版本、插件版本、相关日志。社区渠道分工GitHub Issues用于 bug 报告与功能请求GitHub Discussions用于提问、想法与社区交流一般用法问题打开 Question 类型的 issue。发布流程发布由维护者执行见仓库根 CONTRIBUTING.md 的 Release Process更新 CHANGELOG.md打带注释的 taggit tag -a v5.x.x -m Release v5.x.x推送 taggit push origin v5.x.x由 GitHub Actionsgoreleaser产出发布物。日常 patch 级别的发布则由自动化循环loop-release 工作流按天推进minor/major 版本决策保留给人类。这个项目的独特之处自动化改进循环驱动开发Go Micro 本身是一个 agent harness——它由自主改进循环planner → generator → 独立 evaluator以定时 GitHub Actions 的方式驱动构建见 internal/docs/CONTINUOUS_IMPROVEMENT.md即由 Agent 构建的 Agent harness自我指涉。对人类贡献者而言门禁与自动化贡献完全一致CI 绿、一个 PR 一个关注点生成与评估分离——由 CI 与 harness而非生成者自身作为质量关卡。这也是为什么官方 Quick Start 强调go test ./...、PR 流程强调golangci-lint run并且 Makefile 中专门维护了harness、inner-loop、cli-wayfinding、install-smoke等契约目标它们让任何贡献者都能在没有 LLM API key、没有网络依赖的前提下在本机复现 CI 的判定标准从而把回归拦截在提交之前。结语从git clone到make test-coverage从 Conventional Commits 到插件目录结构从 Hugo 文档站点到 CI 门禁——Go Micro 的贡献路径是清晰且可验证的。对贡献者而言最有价值的起点是先跑通 examples 下的示例如examples/first-agent、examples/support再按本文流程提交你聚焦的第一个 PR。【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
