Cortex 开源贡献指南：从 PR 工作流、代码规范到构建测试的完整实战手册

可观测性时序数据库后端指标监控【免费下载链接】cortexA horizontally scalable, highly available, multi-tenant, long term Prometheus.项目地址https://gitcode.com/gh_mirrors/cortex6/cortex点击查看免费下载Cortex 是一个水平可扩展、高可用、多租户的 Prometheus 长期存储方案采用微服务架构组件既可独立进程运行也可单二进制部署。本文基于仓库官方贡献文档 docs/contributing/_index.md系统梳理向 Cortex 提交代码的完整流程PR 工作流与提交规范、AI 工具使用政策、goimports 代码格式化约定、DCO 签名要求、构建与测试命令、依赖管理、设计模式与代码约定以及文档网站本地预览方式。读完本文你将能按项目标准完成一次从「编码」到「合入」的完整贡献闭环并理解这些规范在仓库源码中的具体落地形式。贡献工作流WorkflowCortex 遵循标准的 GitHub Pull Request 工作流。如果你对该流程不熟悉可先阅读 GitHub 官方提供的 Understanding the GitHub flow 指南。项目欢迎在任何完成度阶段创建draft PR草稿 PR这有助于在开发过程中随时寻求帮助或梳理思路。但一份工作在被标记为完成之前应当满足以下要求组织成清晰的一个或多个提交每个提交的 commit message 应描述该提交所做的全部变更重点说明「为什么改」why而不是「改了什么」what——因为 diff 本身已经展示了代码变化。每个提交都服务于整体目标不要在提交中遗留后来才修正的反复和错误。为新增功能编写单元测试和/或集成测试新功能需要配套测试若是修复 bug则应提供能捕获该 bug 的测试。集成测试的编写与运行方式详见 docs/contributing/how-integration-tests-work.md。必要时补充 CHANGELOG 条目如果 Cortex 的使用者需要了解你的改动如新增/变更/废弃 flag 或行为变化应在 CHANGELOG.md 中登记。从仓库中 CHANGELOG 的实际写法可以看出约定格式条目以[BUGFIX]、[FEATURE]、[CHANGE]、[ENHANCEMENT]等分类前缀开头描述中注明影响范围组件名并在末尾附上关联的 PR 编号如#7861。修改了 flag 或配置时运行make doc若你的改动涉及 CLI flag 或 YAML 配置项必须执行make doc并提交生成的文档文件保证配置文件参考文档与代码保持同步。一旦 PR 被标记为 ready for review系统会自动请求维护者作为 reviewer无需自行寻找。draft PR 在被标记为 ready 之前不会被评审。使用 AI 工具的政策Use of AI ToolsCortex 允许使用生成式 AI 工具辅助贡献但贡献者对其提交的所有内容承担完全责任。如果 AI 生成了贡献的大部分内容例如整个新功能、大规模重构或大量文档请在 PR 描述中如实披露。完整的政策细节见仓库根目录的 GENAI_POLICY.md。从 GENAI_POLICY.md 的正文可以提炼出几条对贡献者有实际约束力的要求理解你提交的每一行代码评审时「这是 AI 写的」不能作为理由你必须能独立解释任何改动。评审并验证 AI 输出不得未经审查就原样提交 AI 生成的内容需核对正确性、警惕幻觉出来的 API 或依赖并确保符合 Cortex 约定。披露大量 AI 参与若 AI 生成了贡献的主体部分需在 PR 描述中说明仅自动补全、小建议等辅助性使用无需披露。遵守 DCO每个提交上的Signed-off-by行对该提交内所有内容含 AI 生成部分都有效。达到同等质量标准AI 辅助贡献同样要满足测试、文档、CHANGELOG、通过 CI 以及符合项目设计模式与代码约定等全部标准。另外GitHub 上的 issue、PR 评审和讨论必须实质性地由人工撰写不得批量提交 AI 生成的评论、评审或 issue 报告。代码格式化与导入分组FormattingCortex 使用goimports工具格式化 Go 文件并排序导入语句安装方式go get golang.org/x/tools/cmd/goimports关键是 goimports 需要配合-local github.com/cortexproject/cortex参数使用将 Cortex 内部导入单独分为一组goimports -local github.com/cortexproject/cortex -w ./path/to/file.go项目希望导入语句保持三个分组组之间用空行分隔标准库standard library第三方包3rd party packagesCortex 内部导入internal Cortex imports。goimports 会修正顺序但会保留组内已有的空行因此需要避免在组内引入多余空行。这一约定在 AGENTS.md 中也有对应说明导入顺序为 stdlib、第三方包、Cortex 内部包以空行分隔。VSCode 推荐配置仓库为 VSCode 用户提供了现成配置 docs/contributing/vscode-goimports-settings.json内容如下{ settings: { go.formatTool: goimports, go.formatFlags: [ -local, github.com/cortexproject/cortex ], go.languageServerExperimentalFeatures: { format: false }, [go]: { editor.codeActionsOnSave: { source.organizeImports: false } }, editor.formatOnSave: true } }该配置将格式化工具指定为 goimports 并带上-local参数同时关闭 gopls 的自动格式化与保存时的 import 整理避免与 goimports 冲突开启保存时自动格式化。Developer Certificate of OriginDCO签名在提交 PR 之前确保所有提交都带有Developer Certificate of Origin签名。示例git commit -s -m Here is my signed commit-s标志会在提交信息中自动附加Signed-off-by行证明你拥有提交该工作的权利且同意 DCO 条款。这是项目合入代码的硬性前置条件漏签的提交会被 DCO 机器人拦截。构建 CortexBuilding Cortex构建二进制在仓库根目录执行make默认情况下构建在Docker 容器中进行使用一个预置了全部所需工具的镜像quay.io/cortexproject/build-image并通过 Docker volume 将你运行make的源码目录挂载进构建容器。从 build-image/Dockerfile 可以看到该镜像预装的内容Go 1.27.0、protobuf 编译器、golangci-lintv2.13.1、misspellv0.3.4、protoc-gen-gogo 系列工具、embedmdv1.0.0等覆盖构建、lint、文档生成等全部环节。如果本机已有完整工具链、不希望经过容器也可以使用make BUILD_IN_CONTAINERfalse在本机构建该选项同样出现在 AGENTS.md 与 Makefile.local.example 的使用场景中。make相关目标定义在根目录 Makefile 中常用目标包括make/make all构建全部内容含各 Dockerfile 对应镜像make exes仅构建二进制./cmd下每个含main.go的目录对应一个可执行文件如cmd/cortex、cmd/query-tee、cmd/thanosconvert等make protos根据*.proto重新生成*.pb.gomake lint运行全部 lint 检查make doc生成配置文档与 JSON Schema。运行单元测试运行单元测试套件go test ./...注意Cortex 的完整 CI 测试使用-tags netgo slicelabels构建标签例如 Makefile 中test目标为go test -tags netgo slicelabels -timeout 30m -race -count 1 ./...如果只在本机快速验证直接go test ./...即可集成测试的完整说明参见 docs/contributing/how-integration-tests-work.md。运行集成测试Cortex 的集成测试用 Go 编写基于仓库自研的 integration/e2e 框架在 Docker 容器中拉起 Cortex 及其依赖组件并使用 Go 标准库testing包做断言。集成测试在每次 PR 的 CI 中都会运行本地开发时只需 Docker也可以轻松执行。先在本地构建集成测试所用的 Cortex Docker 镜像make ./cmd/cortex/.uptodate这会构建quay.io/cortexproject/cortex:latest镜像。当 Cortex 代码cmd/、pkg/或 vendor发生变化时需要重建镜像而开发集成测试本身时不需要重建。镜像就绪后运行全部集成测试go test -v -tagsintegration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...只运行单个测试时可使用-run过滤例如只运行TestRulerAPIShardinggo test -v -tagsintegration,integration_ruler -timeout 2400s -v -count1 ./integration/... -run ^TestRulerAPISharding$集成测试支持的环境变量环境变量作用默认值CORTEX_IMAGE运行 Cortex 所用的 Docker 镜像quay.io/cortexproject/cortex:latestCORTEX_CHECKOUT_DIRCortex 仓库本地 checkout 的绝对路径$GOPATH/src/github.com/cortexproject/cortexE2E_TEMP_DIR测试期间生成临时文件的目录绝对路径系统临时目录E2E_NETWORK_NAME测试创建并使用的 Docker 网络名e2e-cortex-test集成测试文件顶部带有requires_docker构建标签即文件开头//go:build requires_docker行后接空行避免在未安装 Docker 的环境如主包中直接go test ./...被无意执行。隔离性每个集成测试都在独立环境中运行——为每个测试创建独立的 Docker 网络启动 Cortex 及依赖容器向 Cortex 推送/查询序列并执行断言测试结束后Docker 网络与容器都会被终止并删除。从 integration/e2e/scenario.go 的实现可以看到这一机制的底层代码NewScenario()会先清理上次测试可能的残留再通过docker network create创建专属网络并封装Start、StartAndWaitReady、Stop、Kill等生命周期方法测试结束时统一清理网络与容器。依赖管理Dependency managementCortex 使用Go modules管理外部依赖需要 Go 1.11 或更高版本的工作环境以及 git 和 bzr。添加或更新依赖使用go get# 选用最新 tagged release。 go get example.com/some/module/pkg # 选用指定版本。 go get example.com/some/module/pkgvX.Y.Z然后整理go.mod与go.sumgo mod tidy go mod vendor git add go.mod go.sum vendor git commit提交 PR 之前必须提交go.mod和go.sum的变更。Cortex 的依赖是 vendor 化的存放在vendor/目录升级依赖后需用go mod vendor同步 vendor 目录同时注意不要直接修改 vendor 目录下的上游代码。CI 中make mod-check会校验go.mod、go.sum与vendor/的一致性。设计模式与代码约定Design patterns and Code conventions详细的规范见独立页面 docs/contributing/design-patterns-and-conventions.md其要点包括Go 编码风格遵循 Go Code Review Comments 风格指南及 Peter Bourgon 的《Go: Best Practices for Production Environments》中 Formatting and style 一节。禁止全局变量不鼓励在代码中使用全局变量。Prometheus 指标注册指标时不要使用全局变量应通过promauto.With(reg)创建并注册Cortex 内部组件不要注册到默认的 prometheus 注册器而是接收外部传入的prometheus.Registerer例如NewComponent(reg prometheus.Registerer)。测试导出的指标时使用testutil.GatherAndCompare()。这一点在 AGENTS.md 中被再次强调用promauto.With(reg)绝不使用全局 prometheus 注册器。配置与 CLI flag 命名约定配置文件选项小写 下划线分隔snake_case如memcached_clientCLI flag小写 短横线分隔kebab-case如memcached-client新增配置项时先在 docs/configuration/config-file-reference.md 中查找是否有类似选项保持命名一致例如网络端点列表统一叫addresses文档或 changelog 中提及 CLI flag 时一律加单个-前缀。文档与本地网站预览DocumentationCortex 文档会被编译成网站发布。修改文档或网站样式时可按 docs/contributing/how-to-run-website-locally.md 的说明在本地起站点以获得快速反馈。一次性初始设置安装 Hugoextended版本具体版本号可在build-image/Dockerfile中查看安装 Node.js v14 或更高版本安装 Node 依赖cd website npm install cd -安装 embedmd v1.0.0go install github.com/campoy/embedmdv1.0.0执行make BUILD_IN_CONTAINERfalse web-build。本地运行# 保持运行 make web-serve站点运行在http://localhost:1313/。每次修改docs/或仓库根目录下的 markdown 文件后运行make BUILD_IN_CONTAINERfalse web-pre若修改了 Cortex 代码中的配置文件或 CLI flag需要重建配置参考文档make BUILD_IN_CONTAINERfalse doc web-predoc目标在 Makefile 中实现为运行tools/doc-generator从模板生成docs/configuration/config-file-reference.md等文档及 schemas/cortex-config-schema.json。补充说明在 GitHub 上直接浏览部分页面时可能会看到失效链接或页面这是预期现象无需处理——除非它影响了站点构建。从仓库角度理解这些规范的落地以上规范并非纸面约定而是可以在仓库中找到具体实现证据构建流水线make doc、make protos、make lint、make test等目标均定义在 Makefile 中Docker 化构建所需镜像的定义见 build-image/Dockerfile。格式化与 lintlint目标不仅运行 misspell 与 golangci-lint还通过faillint工具强制禁止导入被淘汰的包如sync/atomic必须用go.uber.org/atomic、禁止在 alertmanager 等包中引入全局 logger 等并强制查询路径支持多租户调用。这些约束与「禁止全局变量」「组件内部不注册默认注册器」等代码约定相互呼应。依赖管理仓库根目录的 go.mod、go.sum 与vendor/目录是 Go modules vendor 模式的直接体现make mod-check会在 CI 中校验三者一致性。AI 政策面向人类贡献者的完整规则见 GENAI_POLICY.md与之配套、面向 AI 编码代理的技术指引构建命令、架构、约定见 AGENTS.md两者分工明确前者管「人如何使用 AI 提交贡献」后者管「AI 代理在本仓库工作时如何干活」。集成测试框架e2e 测试基础设施位于 integration/e2e其中 scenario.go 实现了 Docker 网络的创建、服务生命周期管理与测试隔离所有集成测试用例位于 integration 目录并统一带有requires_docker构建标签。结语Cortex 的贡献流程是一套「标准化 自动化」的体系DCO 签名与 AI 披露保证来源可信goimports 三组导入与命名约定保证代码风格统一make doc与 CHANGELOG 保证配置与变更对使用者透明Docker 化构建与 e2e 框架保证任何开发者的本地环境与 CI 行为一致。按照本文梳理的步骤——先按规范编写与格式化代码、补齐测试与文档、运行make与go test验证、签署 DCO 后提交 PR——你就能顺畅地融入 Cortex 的贡献流程并借助仓库内的 Makefile、AGENTS.md 与 GENAI_POLICY.md 持续对照自查。赞分享可观测性时序数据库后端指标监控【免费下载链接】cortexA horizontally scalable, highly available, multi-tenant, long term Prometheus.项目地址https://gitcode.com/gh_mirrors/cortex6/cortex点击查看免费下载相关推荐pyprobml 贡献指南从 PR 工作流到 Notebook 规范化的完整实战手册pyprobml 贡献指南从 PR 工作流到 Notebook 规范化的完整实战手册 导读 本文基于 pyprobml 仓库的 notebooks/contr机器学习深度学习Sanic 贡献指南从源码安装到测试、代码规范与 PR 流程的完整实践手册Sanic 贡献指南从源码安装到测试、代码规范与 PR 流程的完整实践手册 导读 本文基于 Sanic 官方贡献指南仓库内 CONTRIBUTING.md后端Web框架Finagle 贡献指南从源码构建、测试规范到代码评审的完整开发工作流Finagle 贡献指南从源码构建、测试规范到代码评审的完整开发工作流 Finagle 是一个容错、协议无关的 RPC 系统其代码库横跨 finagle c后端RPC框架上一篇Windows电脑秒连iPhone热点苹果官方驱动一键安装终极指南下一篇StarRailAssistant崩坏星穹铁道自动化锄大地实战指南高效解放双手的智能解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考