原文

提交贡献

本文主要讲述了为 Thanos 项目做贡献的流程。

首先，在项目中的所有互动中，请您遵循CODE_OF_CONDUCT（行为准则）。

Thanos 理念

Thanos 和我们社区的理念大量借鉴了 UNIX 理念和 Golang 编程语言。

• 每个子命令应该只做一件事并把它组好。例如：Thanos query 代理组件（的职责是：）为已知的存储 API endpoint

传入调用并且合并结果。

• 编写协同工作的组件（言外之意是编写的组件要能够与外部更好的协同，比如跟 Prometheus）。例如：blocks 应该以原生 Prometheus 格式存储。

• 使组件易于阅读、编写和运行。 降低系统设计和实施的复杂性

反馈/问题

如果您遇到任何问题或有改进的想法，请：

• 首先可以通过 Google 或者 在打开或已关闭的问题（Issues）中寻求答案；

如果您找到（你关心的问题的）相关主题，请对该问题发表评论。

• 如果未找到任何与其相关的问题（Issues），请将（您的）问题添加到 GitHub 问题（Issues）列表中。

（在提问时，）请提供与所提问题相关的任何信息。（具体可参考 Issue 模板：https://github.com/thanos-io/thanos/tree/main/.github/ISSUE_TEMPLATE）。

• 如果您有一个快速的问题，您可能还想在 CNCF 工作区中的 #thanos 或 #thanos-dev slack 频道上提问。

我们建议用 GitHub Issues 来提问（Add issues）和反馈，因为 GitHub Issues 是可追踪的。

如果您遇到与安全相关的漏洞，请参考 《漏洞上报流程》

添加新功能/组件

在对 Thanos 仓库进行复杂更改时，（也许）您想通过 Github Issues、 Slack 或其他方法进行。

请在进行更改之前，请和仓库的 Owner 进行讨论。

向 Thanos 添加大型新功能或/和组件时，

首先应该创建一份提案文档，概述更改的设计决策、更改的动机以及任何您可能已考虑好的替代方案；

通用命名

在代码或文档中，请首选没有攻击性的术语，例如：

• allowlist / denylist (instead of whitelist / blacklist)

• primary / replica (instead of master / slave)

• openbox / closedbox (instead of whitebox / blackbox)

组件命名

Thanos 是一个分布式系统，由此处列出的多个服务和 CLI 工具组成。

当我们以技术能力提及这些组件时，

我们（习惯）使用口头形式：store、compact、rule、query、query_frontend。 这包括：

• 代码

• 指标

• 命令行

• 混合示例：告警、规则、面板；

• 容器名字

• 选项和配置

• 包名字

• 日志信息，以及链路.

然而，当以更一般的方式讨论这些组件时，

我们使用专业名词形式：存储网关、压缩器、规则、查询器、查询前端。 主要包括在以下领域（的使用）：

• 开放的交流

• 文档

• 代码注释

开发

以下部分解释了在 Thanos 开发过程中需要注意的各种建议和过程。

前提条件

• 强烈建议您使用 Linux 发行版系统或 OSX 进行开发。

• Golang 版本需在 V1.13.9+

• 针对 React UI，您需要一个有效的 NodeJS 环境和 npm 包管理器来编译 Web UI 组件。

第一步

熟悉 Thanos 的样式指南和机制比较关键，尤其是当您的贡献涉及 Thanos 分布式系统的多个组件时。 我们推荐：

• 阅读入门指南（getting started docs ） 并完成它们，或者完成 Thanos 教程。

• 熟悉我们的编码风格指南。

• 熟悉 Makefile 命令，例如 format、build、proto、docker 和 test。 make help 将打印大多数可用命令以及相关详细信息。

• 使用 Gitpod.io 启动预构建的开发环境。

• 如果您想在本地开发项目，请在您的机器上安装 Golang。 这里有一个不错的参考。

• 您可以按照此处提到的步骤运行一个交互式示例，该示例也会填充一些数据。

在你本地电脑安装项目工程

• Find any directory in your system your want Thanos repo in. e.g ~/Repos -

• 在您的机器上中寻找一个您想要 存放 Thanos 仓库的目录。例如 ~/Repos -

  cd ~/Repos
  

• 确保设置了 GOBIN、GOPATH 和 GOPROXY（有用的）环境变量，并且环境遍历 PATH 中包含了 GOBIN 。如果您无法访问 https://proxy.golang.org，您可以使用GOPROXY=https://goproxy.cn 替代。例如：

export GOBIN="~/Repos/thanos/.bin" # It's nice to have local tooling installed and stored locally. export GOPATH="~/Repos/thanosgopath" # Use if you want to have an isolated directory for deps, otherwise, the directory where you have installed golang will be used. export GOPROXY="https://proxy.golang.org" export PATH="$GOBIN:$PATH"

• Consider adding the environment variables to your host machine (e.g /.bashrc or .envrc) file so that those environment variables are persisted across sessions.

• 考虑将环境变量添加到您主机的（例如 /.bashrc 或 .envrc）文件中，以便这些环境变量可以跨会话窗口（永久）生效。

• 在 ~/Repos 目录中 Clone Thanos

• For HTTPS - git clone https://github.com/thanos-io/thanos.git
  

• For SSH - git clone git@github.com:thanos-io/thanos.git
  

• Once installed, you can run make help inside Thanos folder for getting a list of helper commands which are provided for making development easy for you :)

• 安装完毕后，您可以在 Thanos 目录中运行 make help 命令并获取命令列表，这些命令可以助您轻松开发:)

构建/运行/开发

• Run make help for getting a list of helper commands that will make your development life much more easy. Especially consider using make lint often. It provides auto linting and formatter for making sure the code quality meets the standards of contribution.

• 运行 make help 可以获取到帮助命令的列表，这些帮助命令将会使您的开发过程更加轻松。

尤其要考虑经常使用 make lint 命令。 该命令会提供自动 linting 和 formatter，这样确保了您的代码质量符合贡献标准。

• Usually, while sending in a PR make build, make format, make lint, make test, make docs, make check-docs, make quickstart are the most used commands while developing Thanos.

• 通常，在发送 PR 时，make build、make format、make lint、make test、make docs、make check-docs、make quickstart 是开发 Thanos 时最常用的命令。

• 当您在 Thanos 仓库的根目录运行 make build 时，旧会编译代码并生成一个名为thanos 的二进制文件并将其构建到您的 $GOBIN 或 $GOPATH/bin 中。

• In case you are working on a component of Thanos, you would love it if you don’t have to set up the yaml configuration for Prometheus and other components, before you start running the component. This is a repetitive task, and the Thanos Community has provided commands/script for automating the running of components -

如果您正在使用 Thanos 的组件，假如在开始运行组件之前无需为 Prometheus 和其他组件设置 yaml 配置，那么您肯定很乐意这样。 这是一项重复性任务，（鉴于此），Thanos 社区提供了用于自动运行组件的命令/脚本

• 运行 make quickstart 可以快速启动 Thanos 的所有组件。

• 如果您想运行特定组件而不是所有组件，可以随意使用和编辑 - quickstart.sh
  

提交请求的流程

Forking and Creating the local setup for developing Thanos

Start your development with forking thanos-io/thanos.git . Here are sample steps to setup your development environment:

通过 fork thanos 官方仓库 thanos-io/thanos.git 您就可以开启您的开发之旅。 以下是设置开发环境的示例步骤

$ GOPATH=$(go env GOPATH)$ mkdir -p $GOPATH/src/github.com/thanos-io$ cd $GOPATH/src/github.com/thanos-io$ git clone https://github.com/<your_github_id>/thanos.git$ cd thanos$ git remote add upstream https://github.com/thanos-io/thanos.git  ## 获取远程 thanos-io/thanos.git 的最新代码$ git remote update ## 更新本地的git分支以便保持跟远端一致.$ git merge upstream/main$ make build$ export PATH=$PATH:$GOPATH/bin$ thanos -h

Signing your work: DCO (Developer Certificate of Origin) Process.

• By contributing to this project you agree to the Developer Certificate of Origin(DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.

为该项目做出贡献即表示您同意开发者原始证书 (DCO)。 本文档由 Linux 内核社区创建，是一个简单的声明，即您作为贡献者，拥有做出贡献的合法权利。

• 如要签署，您需要在提交消息的末尾添加 Signed-off-by: Your Name <your email id>。 您可以使用 git commit -s 执行此操作。 例如：

$ git commit -s -m 'This is my commit message'

• 您还可以在您的 ~/.git 配置中将 commit 设置为 commit -s的别名，以便签署所有未来的提交。

• If you have authored an unsigned commit, you can update it using git commit --amend --signoff. If you've pushed your changes to GitHub already you'll need to force push your branch after this with git push -f.

• 如果您创作了未签名的提交，则可以使用 git commit --amend --signoff 更新它。

如果您已经将更改推送到 GitHub，则需要在此之后使用 git push -f 强制推送您的分支。

1. 保持 PR 尽可能小。 对于您的每个 PR，您都可以根据最新的 main 主干 创建一个新分支。 如果需要，将它们链接起来（将一个 PR 基于其他 PR）。 您可以从此处阅读有关工作流程的更多详细信息。

$ git checkout main$ git remote update$ git merge upstream/main$ git checkout -b <your_branch_for_new_pr>$ make build$ <Iterate your development>$ git push origin <your_branch_for_new_pr>

Tests your changes

Updating your branch

It is a good practice to keep your branch updated by rebasing your branch to main.

通过将（当前）分支更换到 main 来保持分支更新是一个很好的做法。

• Update your main - git checkout main; git pull <remote_name> main
  

• Rebase your main - git rebase -i main
  

Changelog and Review Procedure

日志变更与代码审查的流程

• 如果您的更改会影响到用户（比如添加或删除功能），请考虑将该更添加到更改日志中。

• 一旦您获得至少一位具有写访问权限的开发人员的签字，您就可以合并拉取请求，或者如果您没有这样做的权限，您可以请求第二个审阅者为您合并。

• 如果您觉得您的 PR 等待审核的时间太长，请随时在我们的 slack 上 ping #thanos-dev 频道（以申请）代码审核！

• If you are a new contributor with no write access, you can tag in the respective maintainer for the changes, but be patient enough for the reviews. Remember, good things take time :)

• 如果你是一个没有写权限的新贡献者，你可以在相应的维护者中标记当前更改，但对 reviews 要有足够的耐心。 记住，好事多磨 :)

依赖管理

The Thanos project uses Go modules to manage dependencies on external packages. This requires a working Go environment with version 1.11 or greater and git installed.

To add or update a new dependency, use the go get command:

Thanos 项目使用 Go modules来管理对外部包的依赖。

前提是需要 V1.11 或更高版本并安装了 git 的工作 Go 环境。

要添加或更新新的依赖项，请使用 go get 命令：

# Pick the latest tagged release.go get example.com/some/module/pkg
# Pick a specific version.go get example.com/some/module/pkg@vX.Y.Z

Tidy up the go.mod and go.sum files:

make deps  ## 用make deps 命令来一键整理go modules相关文件.git add go.mod go.sumgit commit

在提交 pull request 之前，您必须提交对 go.mod 和 go.sum 的更改。

运行测试

• Thanos 提供了 make 命令来帮助您在本地运行测试。

• If you don't have a live object store ready, you can use the make test-local command.

• 如果您手头没有真实的对象存储，您可以使用 make test-local 命令。

• NOTE: This command skips tests against live object storage systems by specifying environment variables; this causes the store-specific tests to be run against memory and filesystem object storage types only. The CI tests run uses GCS, AWS and Swift.

注意 ：此命令通过指定环境变量跳过了针对实时对象存储系统的测试； 这会导致特定存储的测试仅针对内存和文件系统对象存储类型运行。 CI 测试运行使用 GCS、AWS 和 Swift。

• 不指定这些变量将导致针对 GCS、AWS、Azure、COS 等的身份验证错误。

• 如果你有一个不错的硬件来运行测试，你可以在本地运行它们。

• If you want to run the tests once in a while, it is suitable for you to send in a PR, the built in CI/CD setup runs the tests for you, which is nice for once in a while run.

如果你想偶尔运行一次测试，那对这种情况而言，发送一个 PR 再合适不过了，因为内置的 CI/CD 步骤会为你运行测试，比较适合偶尔一次。

• make test: Runs all Thanos Go unit tests against each supported version of Prometheus. This excludes tests in ./test/e2e.

针对每个受支持的 Prometheus 版本运行所有 Thanos Go 单元测试。 这不包括 ./test/e2e 中的测试。

• make test-local: Runs test excluding tests for ALL object storage integrations.

运行测试，不包括所有针对对象存储集成的测试。

• make test-e2e: Runs all Thanos e2e docker-based e2e tests from test/e2e. Required access to docker daemon.

从 test/e2e 运行所有基于 Thanos e2e docker 的 e2e 测试。 需要访问 docker 守护进程。

• make test-e2e-local: Runs all thanos e2e tests locally. 在本地运行所有 thanos e2e 测试。

高级测试

At some point during development it is useful, in addition to running unit or e2e tests, to run and play with Thanos components manually. While you can run any component manually by crafting specific flags for a test setup, there are already some nice tools and scripts available. Consider the following methods:

在开发过程中的某些时候，除了运行单元或 e2e 测试之外，手动运行和使用 Thanos 组件也很有用。

虽然您可以通过为测试设置制作特定标志来手动运行任何组件，但已经有一些不错的工具和脚本可用。 考虑以下方法：

• make quickstart: this command spins up a simple setup of all Thanos components.

此命令启动所有 Thanos 组件的简单设置。

• make test-e2e: the e2e tests cover most of the setups and functionality Thanos offers. It's extremely easy to add time.Sleep(10* time.Minute) at certain points in the tests (e.g for compactor here). This way when you run make test-e2e, the test will sleep for some time, allowing you to connect to the setup manually using the port printed in the logs. For example:

e2e 测试涵盖了 Thanos 提供的大部分设置和功能。 在测试的某些点添加 time.Sleep(10* time.Minute) 非常容易（例如此处的压缩器）。 这样，当您运行 make test-e2e 时，测试将休眠一段时间，从而允许您使用日志中打印的端口手动连接到设置。 例如：

querier-1: level=info name=querier-1 ts=2020-04-01T12:53:56.101029491Z caller=http.go:56 service=http/server component=query msg="listening for requests and metrics" address=:80querier-1: level=info name=querier-1 ts=2020-04-01T12:53:56.101106805Z caller=intrumentation.go:48 msg="changing probe status" status=readyquerier-1: level=info name=querier-1 ts=2020-04-01T12:53:56.101290229Z caller=grpc.go:106 service=gRPC/server component=query msg="listening for StoreAPI gRPC" address=:9091Ports for container: e2e_test_store_gateway-querier-1 Mapping: map[80:32825 9091:32824]

This output indicates that the HTTP (80) endpoint will be available on http://localhost:32825. You can quickly craft your own test case with our framework as well!

此输出表明 HTTP (80) 端点将在 http://localhost:32825 上可用。 您也可以使用我们的框架快速制作自己的测试用例！

NOTE: make docker has to work in order for make test-e2e to run. This currently might not work properly on macOS.

注意：make docker 必须工作才能保证 make test-e2e 正常运行。 这目前在 macOS 上可能无法正常工作。