Documented design patterns and code conventions (cortexproject#2305)

* Documented design patterns and code conventions

Signed-off-by: Marco Pracucci <[email protected]>

* Referenced Go coding stlyes

Signed-off-by: Marco Pracucci <[email protected]>

CONTRIBUTING.md

@@ -1,84 +1,3 @@
 # Contributing to Cortex
 
-Welcome! We're excited that you're interested in contributing. Below are some basic guidelines.
-
-## Workflow
-
-Cortex follows a standard GitHub pull request workflow. If you're unfamiliar with this workflow, read the very helpful [Understanding the GitHub flow](https://guides.github.com/introduction/flow/) guide from GitHub.
-
-You are welcome to create draft PRs at any stage of readiness - this
-can be helpful to ask for assistance or to develop an idea. But before
-a piece of work is finished it should:
-
-* Be organised into one or more commits, each of which has a commit message that describes all changes made in that commit ('why' more than 'what' - we can read the diffs to see the code that changed).
-* Each commit should build towards the whole - don't leave in back-tracks and mistakes that you later corrected.
-* Have tests for new functionality or tests that would have caught the bug being fixed.
-* Include a CHANGELOG message if users of Cortex need to hear about what you did.
-* If you have made any changes to flags or config, run `make doc` and commit the changed files to update the config file documentation.
-
-## Formatting
-
-Cortex projects uses `goimports` tool (`go get golang.org/x/tools/cmd/goimports` to install) to format the Go files, and sort imports. We use goimports with `-local github.com/cortexproject/cortex` parameter, to put Cortex internal imports into a separate group. We try to keep imports sorted into three groups: imports from standard library, imports of 3rd party packages and internal Cortex imports. Goimports will fix the order, but will keep existing newlines between imports in the groups. We try to avoid extra newlines like that.
-
-You're using an IDE you may find useful the following settings for the Cortex project:
-
-- [VSCode](https://cortexmetrics.io/docs/contributing/vscode-goimports-settings.json)
-
-
-## Developer Certificates of Origin (DCOs)
-
-Before submitting your work in a pull request, make sure that *all* commits are signed off with a **Developer Certificate of Origin** (DCO). Here's an example:
-
-```shell
-git commit -s -m "Here is my signed commit"
-```
-
-You can find further instructions [here](https://github.com/probot/dco#how-it-works).
-
-## Building Cortex
-
-To build:
-```
-make
-```
-
-(By default, the build runs in a Docker container, using an image built
-with all the tools required. The source code is mounted from where you
-run `make` into the build container as a Docker volume.)
-
-To run the test suite:
-```
-make test
-```
-
-### Dependency management
-
-We uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies on external packages.
-This requires a working Go environment with version 1.11 or greater, git and [bzr](http://wiki.bazaar.canonical.com/Download) installed.
-
-To add or update a new dependency, use the `go get` command:
-
-```bash
-# Pick the latest tagged release.
-go get example.com/some/module/pkg
-
-# Pick a specific version.
-go get example.com/some/module/[email protected]
-```
-
-Tidy up the `go.mod` and `go.sum` files:
-
-```bash
-go mod tidy
-go mod vendor
-git add go.mod go.sum vendor
-git commit
-```
-
-You have to commit the changes to `go.mod` and `go.sum` before submitting the pull request.
-
-### Documentation
-
-The Cortex documentation is compiled into a website published at [cortexmetrics.io](https://cortexmetrics.io/). Please see "[How to run the website locally](./how-to-run-website-locally.md)" for instructions.
-
-Note: if you attempt to view pages on Github, it's likely that you might find broken links or pages. That is expected and should not be addressed unless it is causing issues with the site that occur as part of the build.
+See [https://cortexmetrics.io/docs/contributing/](https://cortexmetrics.io/docs/contributing/).

docs/contributing/_index.md

@@ -0,0 +1,93 @@
+---
+title: Contributing
+linkTitle: "Contributing"
+weight: 10
+menu:
+---
+
+Welcome! We're excited that you're interested in contributing. Below are some basic guidelines.
+
+## Workflow
+
+Cortex follows a standard GitHub pull request workflow. If you're unfamiliar with this workflow, read the very helpful [Understanding the GitHub flow](https://guides.github.com/introduction/flow/) guide from GitHub.
+
+You are welcome to create draft PRs at any stage of readiness - this
+can be helpful to ask for assistance or to develop an idea. But before
+a piece of work is finished it should:
+
+* Be organised into one or more commits, each of which has a commit message that describes all changes made in that commit ('why' more than 'what' - we can read the diffs to see the code that changed).
+* Each commit should build towards the whole - don't leave in back-tracks and mistakes that you later corrected.
+* Have tests for new functionality or tests that would have caught the bug being fixed.
+* Include a CHANGELOG message if users of Cortex need to hear about what you did.
+* If you have made any changes to flags or config, run `make doc` and commit the changed files to update the config file documentation.
+
+## Formatting
+
+Cortex projects uses `goimports` tool (`go get golang.org/x/tools/cmd/goimports` to install) to format the Go files, and sort imports. We use goimports with `-local github.com/cortexproject/cortex` parameter, to put Cortex internal imports into a separate group. We try to keep imports sorted into three groups: imports from standard library, imports of 3rd party packages and internal Cortex imports. Goimports will fix the order, but will keep existing newlines between imports in the groups. We try to avoid extra newlines like that.
+
+You're using an IDE you may find useful the following settings for the Cortex project:
+
+- [VSCode](vscode-goimports-settings.json)
+
+
+## Developer Certificates of Origin (DCOs)
+
+Before submitting your work in a pull request, make sure that *all* commits are signed off with a **Developer Certificate of Origin** (DCO). Here's an example:
+
+```shell
+git commit -s -m "Here is my signed commit"
+```
+
+You can find further instructions [here](https://github.com/probot/dco#how-it-works).
+
+## Building Cortex
+
+To build:
+```
+make
+```
+
+(By default, the build runs in a Docker container, using an image built
+with all the tools required. The source code is mounted from where you
+run `make` into the build container as a Docker volume.)
+
+To run the test suite:
+```
+make test
+```
+
+### Dependency management
+
+We uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies on external packages.
+This requires a working Go environment with version 1.11 or greater, git and [bzr](http://wiki.bazaar.canonical.com/Download) installed.
+
+To add or update a new dependency, use the `go get` command:
+
+```bash
+# Pick the latest tagged release.
+go get example.com/some/module/pkg
+
+# Pick a specific version.
+go get example.com/some/module/[email protected]
+```
+
+Tidy up the `go.mod` and `go.sum` files:
+
+```bash
+go mod tidy
+go mod vendor
+git add go.mod go.sum vendor
+git commit
+```
+
+You have to commit the changes to `go.mod` and `go.sum` before submitting the pull request.
+
+## Design patterns and Code conventions
+
+Please see the dedicated "[Design patterns and Code conventions](design-patterns-and-conventions.md)" page.
+
+## Documentation
+
+The Cortex documentation is compiled into a website published at [cortexmetrics.io](https://cortexmetrics.io/). Please see "[How to run the website locally](./how-to-run-website-locally.md)" for instructions.
+
+Note: if you attempt to view pages on Github, it's likely that you might find broken links or pages. That is expected and should not be addressed unless it is causing issues with the site that occur as part of the build.

docs/contributing/design-patterns-and-conventions.md

@@ -0,0 +1,40 @@
+---
+title: "Design patterns and Code conventions"
+linkTitle: "Design patterns and Code conventions"
+weight: 2
+slug: design-patterns-and-code-conventions
+---
+
+Cortex adopts some design patterns and code conventions that we ask you to follow when contributing to the project. These conventions have been adopted based on the experience gained over the time and aim to enforce good coding practices and keep a consistent UX (ie. config).
+
+## Go coding style
+
+Cortex follows the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) styleguide and the [Formatting and style](https://peter.bourgon.org/go-in-production/#formatting-and-style) section of Peter Bourgon's [Go: Best Practices for Production Environments](https://peter.bourgon.org/go-in-production/).
+
+## No global variables
+
+- Do not use global variables
+
+## Prometheus metrics
+
+When registering a metric:
+
+- Do not use a global variable for the metric
+- Create and register the metric with `promauto.With(reg)`
+- In any internal Cortex component, do not register the metric to the default prometheus registerer, but pick the registerer in input (ie. `NewComponent(reg prometheus.Registerer)`)
+
+Testing metrics:
+
+- When writing using tests, test exported metrics using `testutil.GatherAndCompare()`
+
+## Config file and CLI flags conventions
+
+Naming:
+
+- Config file options should be lowercase with words `_` (underscore) separated (ie. `memcached_client`)
+- CLI flags should be lowercase with words `-` (dash) separated (ie. `memcached-client`)
+- When adding a new config option, look if a similar one already exists within the [config](../configuration/config-file-reference.md) and keep the same naming (ie. `addresses` for a list of network endpoints)
+
+Documentation:
+
+- A CLI flag mentioned in the documentation or changelog should be always prefixed with a single `-` (dash)

docs/contributing/how-to-run-website-locally.md

@@ -1,7 +1,7 @@
 ---
 title: "How to run the website locally"
 linkTitle: "How to run the website locally"
-weight: 2
+weight: 3
 slug: how-to-run-the-website-locally
 ---
 

docs/contributing/how-to-upgrade-golang-version.md

@@ -1,7 +1,7 @@
 ---
 title: "How to upgrade Golang version"
 linkTitle: "How to upgrade Golang version"
-weight: 3
+weight: 4
 slug: how-to-upgrade-golang-version
 ---
 

tools/website/web-pre.sh

@@ -16,10 +16,9 @@ mkdir -p ${OUTPUT_CONTENT_DIR}
 cp -r ${ORIGINAL_CONTENT_DIR}/* ${OUTPUT_CONTENT_DIR}
 cp -r code-of-conduct.md CHANGELOG.md ${OUTPUT_CONTENT_DIR}
 cp GOVERNANCE.md ${OUTPUT_CONTENT_DIR}/governance/_index.md
-cp CONTRIBUTING.md ${OUTPUT_CONTENT_DIR}/contributing/_index.md
 cp images/* ${WEBSITE_DIR}/static/images
 
-# Add headers to special CODE_OF_CONDUCT.md, CONTRIBUTING.md and CHANGELOG.md files.
+# Add headers to special CODE_OF_CONDUCT.md and CHANGELOG.md files.
 echo "$(cat <<EOT
 ---
 title: Code of Conduct
@@ -42,17 +41,6 @@ EOT
 )" > ${OUTPUT_CONTENT_DIR}/CHANGELOG.md
 tail -n +2 CHANGELOG.md >> ${OUTPUT_CONTENT_DIR}/CHANGELOG.md
 
-echo "$(cat <<EOT
----
-title: Contributing
-type: docs
-originalpath: CONTRIBUTING.md
-weight: 10
----
-EOT
-)" > ${OUTPUT_CONTENT_DIR}/contributing/_index.md
-tail -n +2 CONTRIBUTING.md >> ${OUTPUT_CONTENT_DIR}/contributing/_index.md
-
 echo "$(cat <<EOT
 ---
 title: Governance