This document explain the process of contributing to the Thanos project.
First of all please follow the code of conduct in all your interactions with the project.
Table of contents generated with markdown-toc
The philosophy of Thanos and our community is borrowing much from UNIX philosophy and the golang programming language.
If you encounter any issue or you have an idea to improve, please:
If you encounter security vulnerability, please refer to Reporting a Vulnerability process
When contributing not obvious change to Thanos repository, please first discuss the change you wish to make via issue or slack, or any other method with the owners of this repository before making a 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.
Thanos is a distributed system composed with several services and CLI tools as listed here.
When we refer to them as technical reference we use verb form:
query. This includes:
However, when speaking about those or explaining we use
actor noun form:
store gateway, compactor, ruler, querier. This includes areas like:
The following section explains various suggestions and procedures to note during development of Thanos.
It’s key to get familiarized with style guide and mechanics of Thanos, especially if your contribution touches more than one component of the Thanos distributed system. We recommend:
make helpwill print most of available commands with details.
$ 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/master $ make build $ export PATH=$PATH:$GOPATH/bin $ thanos -h
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.
To signoff, you need to add
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'
You can also alias
commit -s in your
~/.gitconfig to signoff all your future commits.
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 checkout master $ git remote update $ git merge upstream/master $ git checkout -b <your_branch_for_new_pr> $ make build $ <Iterate your development> $ git push origin <your_branch_for_new_pr>
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 storages only. The CI tests run
make test-ci instead
(uses GCS, AWS).
Not specifying these variables will result in auth errors against GCS, AWS, Azure, COS etc.
#thanos-prschannel 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
make deps git add go.mod go.sum git commit
You have to commit the changes to
go.sum before submitting the pull request.
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 buildbefore running the script to build the
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.Minutes)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.