Skip to content
Snippets Groups Projects

Add Go guidelines to developer docs

Merged Philippe Lafoucrière requested to merge docs/go-standards into master
@@ -6,7 +6,7 @@ projects using the [Go language][go].
## Overview
GitLab is built on top of [Ruby on Rails][rails], but we're also using [Go][go]
for projects where it makes sense. [Go][go] is a very powerful languages, with
for projects where it makes sense. [Go][go] is a very powerful language, with
many advantages, and is best suited for projects with a lot of IO (disk/network
access), http requests, parallel processing, etc. Since we have both [Ruby on
Rails][rails] and [Go][go] at GitLab, we should evaluate carefully which of the
@@ -24,20 +24,18 @@ https://github.com/golang/go/wiki/CodeReviewComments
Reviewers and maintainers should pay attention to:
- defer functions (add examples here)
- `defer` functions: Ensure presence when needed, and after `err` check.
- inject dependencies as parameters
- void structs when marshalling to JSON (generates `null` instead of `[]`)
TODO: Give examples
### Security
Security is our top-priority at GitLab. During code reviews, we must take care
of possible security breaches in our code:
- XSS using text/template
- XSS when using text/template
- CSRF Protection using Gorilla
- Use a Go version without know vulnerabilities
- Use a Go version without known vulnerabilities
- Don't leak secret tokens
- SQL injections
@@ -56,8 +54,7 @@ have a shared pool of Go reviewers at GitLab. To find a reviewer, use the
page in the handbook. "GitLab Community Edition (CE)" and "GitLab Community
Edition (EE)" both have a "Go" section with its list of reviewers.
To add yourself as a GitLab Go reviewer, add the gitlab-ce and/or ee `go`
subproject to the
To add yourself to this list, add the following to your profile in the
[team.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/team.yml)
file.
@@ -71,7 +68,7 @@ projects:
- Avoid global variables, even in packages. Doing so will introduce side
effects if the package is included multiple times.
- Use `go fmt` before commiting
- Use `go fmt` before committing
### Automatic linting
@@ -116,7 +113,7 @@ databases.
### Migrations
In the rare eventually of managing a hosted database, it's necessary to use a
In the rare event of managing a hosted database, it's necessary to use a
migration system like ActiveRecord is providing. One simple library can be
used: https://github.com/db-journey/journey It was designed to be used in
`postgres` containers, that can be deployed as long-running pods. New versions
@@ -124,11 +121,12 @@ will deploy a new pod, migrating the data automatically.
## Testing
We don't use any specific framework for testing, as the standard library
provides already everything to get started. Some external libraries might be
used if needed:
We should not use any specific library or framework for testing, as the standard library
provides already everything to get started. For example, some external dependencies might be
worth considering in case we decide to use a specific library or framework:
- https://github.com/stretchr/testify
- ?
- https://github.com/gavv/httpexpect
Use [subtests](https://blog.golang.org/subtests) whenever possible to improve
code readability and test output.
@@ -142,7 +140,7 @@ Benchmarks, to ensure performance consistency over time.
Every Go program is launched from the command line.
[cli](https://github.com/urfave/cli) is a convenient package to create command
line apps. It should be used whether the project is a daemon or a simple cli
line apps. It should be used whether the project is a daemon or a simple cli
tool. Flags can be mapped to [environment
variables](https://github.com/urfave/cli#values-from-the-environment) directly,
which documents and centralizes at the same time all the possible command line
@@ -155,7 +153,7 @@ in the code.
The usage of a logging library is strongly recommended for daemons. Even though
there is a `log` package in the standard library, we generally use
[logrus](https://github.com/sirupsen/logrus). Its plugin ("hooks") system
[logrus](https://github.com/sirupsen/logrus). Its plugin ("hooks") system
makes it a powerful logging library, with the ability to add notifiers and
formatters at the logger level directly.
@@ -173,7 +171,7 @@ functionality:
for distributed tracing.
This gives us a thin abstraction over underlying implementations that is
consistent across Workhorse, Gitaly, and, in future, other Go servers. For
consistent across Workhorse, Gitaly, and, in future, other Go servers. For
example, in the case of `gitlab.com/gitlab-org/labkit/tracing` we can switch
from using Opentracing directly to using Zipkin or Gokit's own tracing wrapper
without changes to the application code, while still keeping the same
@@ -184,7 +182,7 @@ variable).
Since daemons are long-running applications, they should have mechanisms to
manage cancellations, and avoid unnecessary resources consumption (which could
lead to DDOS vulnerabilities). Go Context should be used in functions that can
lead to DDOS vulnerabilities). Go Context should be used in functions that can
block, and passed as the first parameter:
https://github.com/golang/go/wiki/CodeReviewComments#contexts
@@ -192,7 +190,7 @@ https://github.com/golang/go/wiki/CodeReviewComments#contexts
## Dockerfiles
Every project should have a `Dockerfile` at the root of their repository, to
build and run the project. Since Go program are static binaries, they should
build and run the project. Since Go program are static binaries, they should
not require any external dependency, and shells in the final image are useless.
We encourage [Multistage
builds](https://docs.docker.com/develop/develop-images/multistage-build/):
Loading