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

• 可观测性
• 时序数据库
• 后端
• 指标监控

Cortex 是一个水平可扩展、高可用、多租户的 Prometheus 长期存储方案，采用微服务架构，组件既可独立进程运行也可单二进制部署。本文基于仓库官方贡献文档 docs/contributing/_index.md，系统梳理向 Cortex 提交代码的完整流程：PR 工作流与提交规范、AI 工具使用政策、goimports 代码格式化约定、DCO 签名要求、构建与测试命令、依赖管理、设计模式与代码约定，以及文档网站本地预览方式。读完本文，你将能按项目标准完成一次从「编码」到「合入」的完整贡献闭环，并理解这些规范在仓库源码中的具体落地形式。

贡献工作流（Workflow）

Cortex 遵循标准的 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 Tools）

Cortex 允许使用生成式 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 报告。

代码格式化与导入分组（Formatting）

Cortex 使用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

项目希望导入语句保持三个分组（组之间用空行分隔）：

1. 标准库（standard library）；
2. 第三方包（3rd party packages）；
3. Cortex 内部导入（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 Origin（DCO）签名

在提交 PR 之前，确保所有提交都带有Developer Certificate of Origin签名。示例：

git commit -s -m "Here is my signed commit"

-s标志会在提交信息中自动附加Signed-off-by行，证明你拥有提交该工作的权利，且同意 DCO 条款。这是项目合入代码的硬性前置条件，漏签的提交会被 DCO 机器人拦截。

构建 Cortex（Building Cortex）

构建二进制

在仓库根目录执行：

make

默认情况下，构建在Docker 容器中进行：使用一个预置了全部所需工具的镜像（quay.io/cortexproject/build-image），并通过 Docker volume 将你运行make的源码目录挂载进构建容器。从 build-image/Dockerfile 可以看到该镜像预装的内容：Go 1.27.0、protobuf 编译器、golangci-lint（v2.13.1）、misspell（v0.3.4）、protoc-gen-gogo 系列工具、embedmd（v1.0.0）等，覆盖构建、lint、文档生成等全部环节。

如果本机已有完整工具链、不希望经过容器，也可以使用make BUILD_IN_CONTAINER=false在本机构建（该选项同样出现在 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.go；
• make 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 -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/...

只运行单个测试时可使用-run过滤，例如只运行TestRulerAPISharding：

go test -v -tags=integration,integration_ruler -timeout 2400s -v -count=1 ./integration/... -run "^TestRulerAPISharding$"

集成测试支持的环境变量：

集成测试文件顶部带有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 management）

Cortex 使用Go modules管理外部依赖，需要 Go 1.11 或更高版本的工作环境，以及 git 和 bzr。

添加或更新依赖使用go get：

# 选用最新 tagged release。 go get example.com/some/module/pkg # 选用指定版本。 go get example.com/some/module/pkg@vX.Y.Z

然后整理go.mod与go.sum：

go 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_client；
• CLI flag：小写 + 短横线分隔（kebab-case），如memcached-client；
• 新增配置项时，先在 docs/configuration/config-file-reference.md 中查找是否有类似选项，保持命名一致（例如网络端点列表统一叫addresses）；
• 文档或 changelog 中提及 CLI flag 时，一律加单个-前缀。

文档与本地网站预览（Documentation）

Cortex 文档会被编译成网站发布。修改文档或网站样式时，可按 docs/contributing/how-to-run-website-locally.md 的说明在本地起站点以获得快速反馈。

一次性初始设置：

1. 安装 Hugo（extended版本），具体版本号可在build-image/Dockerfile中查看；
2. 安装 Node.js v14 或更高版本；
3. 安装 Node 依赖：cd website && npm install && cd -；
4. 安装 embedmd v1.0.0：go install github.com/campoy/embedmd@v1.0.0；
5. 执行make BUILD_IN_CONTAINER=false web-build。

本地运行：

# 保持运行 make web-serve

站点运行在http://localhost:1313/。

• 每次修改docs/或仓库根目录下的 markdown 文件后，运行make BUILD_IN_CONTAINER=false web-pre；
• 若修改了 Cortex 代码中的配置文件或 CLI flag，需要重建配置参考文档：make BUILD_IN_CONTAINER=false doc web-pre（doc目标在 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。
• 格式化与 lint：lint目标不仅运行 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 持续对照自查。

• 可观测性
• 时序数据库
• 后端
• 指标监控