This document explains the process of contributing to the Thanos project.
First of all please follow the CODE_OF_CONDUCT in all your interactions within the project.
The philosophy of Thanos and our community borrows heavily from UNIX philosophy and the Golang programming language.
If you encounter any issue or you have an idea to improve, please:
If you encounter a security vulnerability, please refer to Reporting a Vulnerability process
When contributing a complex change to Thanos repository, please discuss the change you wish to make within a Github issue, in Slack, or by another method with the owners of this repository before making the change.
Adding a large new feature or/and component to Thanos should be done by first creating a proposal document outlining the design decisions of the change, motivations for the change, and any alternatives that might have been considered.
In the code and documentation prefer non-offensive terminology, for example:
denylist (instead of
replica (instead of
closedbox (instead of
Thanos is a distributed system comprised of several services and CLI tools as listed here.
When we refer to them in a technical capacity we use the verbal form:
query-frontend. This includes:
However, when discussing these components in a more general manner we use the
actor noun form:
query frontend. This includes areas like:
The following section explains various suggestions and procedures to note during development of Thanos.
service.spec.sessionAffinity: ClientIP, it will break things until it’s removed1.
It’s key to get familiarized with the style guide and mechanics of Thanos, especially if your contribution touches more than one component of the Thanos distributed system. We recommend:
make help will print most of available commands with relevant details.
Make sure that the GOBIN, GOPATH and GOPROXY (useful) environment variables are set and that GOBIN is included in your PATH. You may use
GOPROXY=https://goproxy.cn as an alternative if you cannot visit
https://proxy.golang.org. For example -
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.
Consider adding the environment variables to your host machine (e.g
.envrc) file so that those environment variables are persisted across sessions.
~/Repos folder -
git clone https://github.com/thanos-io/thanos.git
git clone email@example.com:thanos-io/thanos.git
make help inside Thanos folder for getting a list of helper commands which are provided for making development easy for you :)
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 quickstart are the most used commands while developing Thanos.
make build from Thanos repo root, code is compiled and a binary named
thanos is created and built into your
make quickstart for spinning up all components of Thanos quickly.
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:
$ 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
$ git remote update
$ git merge upstream/main
$ make build
$ export PATH=$PATH:$GOPATH/bin
$ thanos -h
Signing your work: DCO (Developer Certificate of Origin) Process.
Signed-off-by: Your Name <your email id> at the end of your commit messages. You can do this using
git commit -s. For example:
$ git commit -s -m 'This is my commit message'
commit -s in your
~/.gitconfig to signoff all your future commits.
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 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
First of all, fall back to
make help to see all availible commands. There are a few checks that happen when making a PR and these need to pass. We can make sure locally before making the PR by using commands that are related to your changes:
make docs generates, formats and cleans up white noise.
make changed-docs does same as above, but just for changed docs by checking
git diff on which files are changed.
make check-docs generates, formats, cleans up white noise and checks links. Since it can be annoying to wait on link check results - it takes forever - to skip the check, you can use
make format formats code
If you only made documentation changes, which do not include a link, you will be fine by using
make docs. If you also changed some code, run
make format as well.
Updating your branch
It is a good practice to keep your branch updated by rebasing your branch to main.
git checkout main; git pull <remote_name> main
git rebase -i main
Changelog and Review Procedure
#thanos-dev channel on our slack for a review!
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:
# 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
git add go.mod go.sum
You have to commit the changes to
go.sum before submitting the pull request.
make test-local command.
make test: Runs all Thanos Go unit tests against each supported version of Prometheus. This excludes tests in
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.
make test-e2e-local: Runs all thanos e2e tests locally.
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:
make quickstart: this command spins up a simple setup of all Thanos components.
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:
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=:80
querier-1: level=info name=querier-1 ts=2020-04-01T12:53:56.101106805Z caller=intrumentation.go:48 msg="changing probe status" status=ready
querier-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=:9091
Ports 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!
make docker has to work in order for
make test-e2e to run. This currently might not work properly on macOS.