Improved documentation. (thanos-io#2053)

Fixes: thanos-io#1389
Fixes: thanos-io#2052

Signed-off-by: Bartlomiej Plotka <[email protected]>

CONTRIBUTING.md

@@ -1,10 +1,8 @@
 # Contributing
 
-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.
+This document explain the process of contributing to the Thanos project.
 
-Please follow the [code of conduct](CODE_OF_CONDUCT.md) in all your interactions with the project.
+First of all please follow the [code of conduct](CODE_OF_CONDUCT.md) in all your interactions with the project.
 
 ## Thanos Philosophy
 
@@ -17,19 +15,39 @@ The philosophy of Thanos and our community is borrowing much from UNIX philosoph
 * Make it easy to read, write, and, run components
   * e.g. reduce complexity in system design and implementation
 
+## Feedback / Issues
+
+If you encounter any issue or you have an idea to improve, please:
+
+* Search through Google and [existing open and closed GitHub Issues](https://github.com/thanos-io/thanos/issues) for the
+answer first. If you find relevant topic, please comment on the issue.
+* If not found, please add an issue to [GitHub issues](https://github.com/thanos-io/thanos/issues). Please provide
+all relevant information as template suggest.
+* If you have a quick question you might want to also ask on #thanos or #thanos-dev slack channel in the CNCF workspace.
+We are recommending, using GitHub issues for issues and feedback, because GitHub issues are track-able.
+
+If you encounter security vulnerability, please refer to [Reporting a Vulnerability process](SECURITY.md)
+
 ## Adding New Features / Components
 
-Adding large new features and components to Thanos should be done by first creating a [proposal](docs/proposals) document outlining the design decisions of the change, motivations for the change, and any alternatives that might have been considered.
+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](docs/proposals) document outlining the design decisions of the change, motivations for the change, and any alternatives that might have been considered.
 
 ## Prerequisites
 
 * It is strongly recommended that you use OSX or popular Linux distributions systems e.g. Ubuntu, Redhat, or OpenSUSE for development.
 
 ## Pull Request Process
 
+
 1. Read [getting started docs](docs/getting-started.md) and prepare Thanos.
-2. Familiarize yourself with [Makefile](Makefile) commands like `format`, `build`, `proto` and `test`.
-3. Fork thanos-io/thanos.git and start development from your own fork. Here are sample steps to setup your development environment:
+2. Familiarize yourself with Go standard style guides Thanos follows: [this](https://golang.org/doc/effective_go.html) and [this](https://github.com/golang/go/wiki/CodeReviewComments).
+3. Familiarize yourself with [Makefile](Makefile) commands like `format`, `build`, `proto` and `test`.
+4. Fork thanos-io/thanos.git and start development from your own fork. Here are sample steps to setup your development environment:
+
 ```console
 $ mkdir -p $GOPATH/src/github.com/thanos-io
 $ cd $GOPATH/src/github.com/thanos-io
@@ -41,7 +59,9 @@ $ git merge upstream/master
 $ make build
 $ ./thanos -h
 ```
-4. Keep PRs as small as possible. For each of your PR, you create one branch based on the latest master. Chain them if needed (base PR on other PRs). Here are sample steps you can follow. You can get more details about the workflow from [here](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
+
+5. Keep PRs as small as possible. For each of your PR, you create one branch based on the latest master. Chain them if needed (base PR on other PRs). Here are sample steps you can follow. You can get more details about the workflow from [here](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
+
 ```console
 $ git checkout master
 $ git remote update
@@ -51,16 +71,18 @@ $ make build
 $ <Iterate your development>
 $ git push origin <your_branch_for_new_pr>
 ```
-5. If you don't have a live object store ready add this envvar to skip tests for these:
+
+6. Add unit tests for new functionalities. Add e2e tests if functionality is major.
+7. If you don't have a live object store ready add this envvar to skip tests for these:
 - THANOS_TEST_OBJSTORE_SKIP=GCS,S3,AZURE,SWIFT,COS,ALIYUNOSS
 
 If you skip all of these, the store specific tests will be run against memory object storage only.
 CI runs GCS and inmem tests only for now. Not having these variables will produce auth errors against GCS, AWS, Azure or COS tests.
 
-6. If your change affects users (adds or removes feature) consider adding the item to [CHANGELOG](CHANGELOG.md)
-7. You may merge the Pull Request in once you have the sign-off of at least one developers with write access, or if you
+8. If your change affects users (adds or removes feature) consider adding the item to [CHANGELOG](CHANGELOG.md)
+9. You may merge the Pull Request in once you have the sign-off of at least one developers with write access, or if you
    do not have permission to do that, you may request the second reviewer to merge it for you.
-8. If you feel like your PR waits too long for a review, feel free to ping [`#thanos-prs`](https://slack.cncf.io/) channel on our slack for review!
+10. If you feel like your PR waits too long for a review, feel free to ping [`#thanos-prs`](https://slack.cncf.io/) channel on our slack for review!
 
 ## Dependency management
 

README.md

@@ -2,9 +2,10 @@
 
 [![CircleCI](https://circleci.com/gh/thanos-io/thanos.svg?style=svg)](https://circleci.com/gh/thanos-io/thanos)
 [![Go Report Card](https://goreportcard.com/badge/github.com/thanos-io/thanos)](https://goreportcard.com/report/github.com/thanos-io/thanos)
-[![GoDoc](https://godoc.org/github.com/thanos-io/thanos?status.svg)](https://godoc.org/github.com/thanos-io/thanos)
+[![Go Code reference](https://img.shields.io/badge/code%20reference-go.dev-darkblue.svg)](https://pkg.go.dev/github.com/thanos-io/thanos?tab=subdirectories)
 [![Slack](https://img.shields.io/badge/join%20slack-%23thanos-brightgreen.svg)](https://slack.cncf.io/)
 [![Netlify Status](https://api.netlify.com/api/v1/badges/664a5091-934c-4b0e-a7b6-bc12f822a590/deploy-status)](https://app.netlify.com/sites/thanos-io/deploys)
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/3048/badge)](https://bestpractices.coreinfrastructure.org/projects/3048)
 
 ## Overview
 

SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+As the Thanos team we are not security experts. However we try our best to avoid security concerns or to avoid
+writing features that handles sensitive information at all.
+
+It's worth to note that we assume the metric data to be sensitive and important.
+External labels and query API parameters are treated as less sensitive, as they are logged and put into metric/traces.
+
+## What you CAN expect:
+
+* We follow best programming practices. We test heavily including e2e tests against major object storages. We use vetting
+and static analysis tool on every PR. We use secure protocols for building process (e.g to produce docker images)
+* We don't log or put into our instrumentation any data that is stored in TSDB block.
+* If we use crypto tools we always rely on FLOSS and standard libraries like official [Go crypt](https://golang.org/pkg/crypto/)
+  library.
+* We always use TLS by default for communication with all object storages.
+* We use stable Go versions to build our images and binaries. We update Go version as soon as new one is released.
+* We use only FLOSS tools.
+
+## What we DON'T do (yet):
+
+* We don't encrypt metric on local storage (e.g on disk). We don't do client encryption for object storage. We recommend
+setting server side encryption for object storage.
+* We don't allow to specify authorization or TLS for Thanos server HTTP APIs.
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.10.1   | :white_check_mark: |
+| < 0.10.1   | :x:                |
+
+## Reporting a Vulnerability
+
+If you encounter security vulnerability, please let us know privately via Thanos Team email: [email protected]

docs/getting-started.md

@@ -98,14 +98,35 @@ We also have example Grafana dashboards [here](/examples/dashboards/dashboards.m
 
 * 02.2018: [Very first Prometheus Meetup Slides](https://www.slideshare.net/BartomiejPotka/thanos-global-durable-prometheus-monitoring)
 * 02.2019: [FOSDEM + demo](https://fosdem.org/2019/schedule/event/thanos_transforming_prometheus_to_a_global_scale_in_a_seven_simple_steps/)
+* 03.2019: [Alibaba Cloud user story](https://www.youtube.com/watch?v=ZS6zMksfipc)
 * 09.2019: [CloudNative Warsaw Slides](https://docs.google.com/presentation/d/1cKpbJY3jIAtr03M-zcNujwBA38_LDj7NqE4LjNfvglE/edit?usp=sharing)
 * 11.2019: [CloudNative Deep Dive](https://www.youtube.com/watch?v=qQN0N14HXPM)
 * 11.2019: [CloudNative Intro](https://www.youtube.com/watch?v=m0JgWlTc60Q)
+* 2019: [Prometheus in Practice: HA with Thanos](https://www.slideshare.net/ThomasRiley45/prometheus-in-practice-high-availability-with-thanos-devopsdays-edinburgh-2019)
 
 ## Blog posts
 
-* 2018: [Introduction blog post](https://improbable.io/games/blog/thanos-prometheus-at-scale)
-* 2019: [Metric monitoring architecture](https://improbable.io/blog/thanos-architecture-at-improbable)
+* 2018:
+
+  * [Introduction blog post](https://improbable.io/games/blog/thanos-prometheus-at-scale)
+  * [Monzo user story](https://monzo.com/blog/2018/07/27/how-we-monitor-monzo)
+  * [Banzai Cloud hand's on](https://banzaicloud.com/blog/hands-on-thanos/)
+  * [uSwitch user story](https://medium.com/uswitch-labs/making-prometheus-more-awesome-with-thanos-fbec8c6c28ad)
+  * [Thanos usage](https://www.infracloud.io/thanos-ha-scalable-prometheus/)
+
+* 2019:
+
+  * [Metric monitoring architecture](https://improbable.io/blog/thanos-architecture-at-improbable)
+  * [Red Hat user story](https://blog.openshift.com/federated-prometheus-with-thanos-receive/)
+  * [HelloFresh blog posts part 1](https://engineering.hellofresh.com/monitoring-at-hellofresh-part-1-architecture-677b4bd6b728)
+  * [HelloFresh blog posts part 2](https://engineering.hellofresh.com/monitoring-at-hellofresh-part-2-operating-the-monitoring-system-8175cd939c1d)
+  * [Thanos deployment](https://www.metricfire.com/blog/ha-kubernetes-monitoring-using-prometheus-and-thanos)
+  * [Taboola user story](https://engineering.taboola.com/monitoring-and-metering-scale/)
+  * [Thanos via Prometheus Operator](https://kkc.github.io/2019/02/10/prometheus-operator-with-thanos/)
+
+* 2020:
+
+  * [Banzai Cloud user story](https://monzo.com/blog/2018/07/27/how-we-monitor-monzo)
 
 ## Integrations
 

docs/release-process.md

@@ -5,6 +5,8 @@ menu: thanos
 slug: /release-process.md
 ---
 
+# Release Process
+
 This page describes the release cadence and process for Thanos project.
 
 We use [Semantic Versioning](http://semver.org/).

scripts/websitepreprocess.sh

@@ -42,7 +42,7 @@ menu: contributing
 ---
 EOT
 )" > ${OUTPUT_CONTENT_DIR}/CODE_OF_CONDUCT.md
-tail -n +2 CODE_OF_CONDUCT.md >> ${OUTPUT_CONTENT_DIR}/CODE_OF_CONDUCT.md
+cat CODE_OF_CONDUCT.md >> ${OUTPUT_CONTENT_DIR}/CODE_OF_CONDUCT.md
 
 echo "$(cat <<EOT
 ---
@@ -52,7 +52,7 @@ menu: contributing
 ---
 EOT
 )" > ${OUTPUT_CONTENT_DIR}/CONTRIBUTING.md
-tail -n +2 CONTRIBUTING.md >> ${OUTPUT_CONTENT_DIR}/CONTRIBUTING.md
+cat CONTRIBUTING.md >> ${OUTPUT_CONTENT_DIR}/CONTRIBUTING.md
 
 echo "$(cat <<EOT
 ---
@@ -62,7 +62,7 @@ menu: thanos
 ---
 EOT
 )" > ${OUTPUT_CONTENT_DIR}/CHANGELOG.md
-tail -n +2 CHANGELOG.md >> ${OUTPUT_CONTENT_DIR}/CHANGELOG.md
+cat CHANGELOG.md >> ${OUTPUT_CONTENT_DIR}/CHANGELOG.md
 
 echo "$(cat <<EOT
 ---
@@ -72,7 +72,17 @@ menu: thanos
 ---
 EOT
 )" > ${OUTPUT_CONTENT_DIR}/MAINTAINERS.md
-tail -n +2 MAINTAINERS.md >> ${OUTPUT_CONTENT_DIR}/MAINTAINERS.md
+cat MAINTAINERS.md >> ${OUTPUT_CONTENT_DIR}/MAINTAINERS.md
+
+echo "$(cat <<EOT
+---
+title: Security
+type: docs
+menu: thanos
+---
+EOT
+)" > ${OUTPUT_CONTENT_DIR}/SECURITY.md
+cat SECURITY.md >> ${OUTPUT_CONTENT_DIR}/SECURITY.md
 
 # Glob again to include new docs.
 ALL_DOC_CONTENT_FILES=$(echo "${OUTPUT_CONTENT_DIR}/**/*.md ${OUTPUT_CONTENT_DIR}/*.md")

website/layouts/_default/baseof.html

@@ -64,6 +64,7 @@ <h6 class="font-weight-bold">Documentation</h6>
                         <li><a class="text-reset" href="{{ "/storage.md" | relURL }}">Storage</a></li>
                         <li><a class="text-reset" href="{{ "/service-discovery.md" | relURL }}">Service Discovery</a></li>
                         <li><a class="text-reset" href="{{ "/maintainers" | relURL }}">Maintainers</a></li>
+                        <li><a class="text-reset" href="{{ "/contributing" | relURL }}">Contributing</a></li>
                     </ul>
                 </div>
                 <div class="col-12 col-md-6 col-lg">