diff options
Diffstat (limited to 'doc/development/go_guide/index.md')
| -rw-r--r-- | doc/development/go_guide/index.md | 74 |
1 files changed, 10 insertions, 64 deletions
diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 0ee73da48db..44f8924be04 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -23,6 +23,16 @@ experiences. Several projects were started with different standards and they can still have specifics. They are described in their respective `README.md` or `PROCESS.md` files. +## Go language versions + +The Go upgrade documentation [provides an overview](go_upgrade.md#overview) +of how GitLab manages and ships Go binary support. + +If a GitLab component requires a newer version of Go, please +follow the [upgrade process](go_upgrade.md#updating-go-version) to ensure no customer, team, or component is adversely impacted. + +Sometimes, individual projects must also [manage builds with multiple versions of Go](go_upgrade.md#supporting-multiple-go-versions). + ## Dependency Management Go uses a source-based strategy for dependency management. Dependencies are @@ -417,70 +427,6 @@ Generated Docker images should have the program at their `Entrypoint` to create portable commands. That way, anyone can run the image, and without parameters it displays its help message (if `cli` has been used). -## Distributing Go binaries - -With the exception of [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner), -which publishes its own binaries, our Go binaries are created by projects -managed by the [Distribution group](https://about.gitlab.com/handbook/product/categories/#distribution-group). - -The [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) project creates a -single, monolithic operating system package containing all the binaries, while -the [Cloud-Native GitLab (CNG)](https://gitlab.com/gitlab-org/build/CNG) project -publishes a set of Docker images and Helm charts to glue them together. - -Both approaches use the same version of Go for all projects, so it's important -to ensure all our Go-using projects have at least one Go version in common in -their test matrices. You can check the version of Go currently being used by -[Omnibus](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/blob/master/docker/Dockerfile_debian_10#L59), -and the version being used for [CNG](https://gitlab.com/gitlab-org/build/cng/blob/master/ci_files/variables.yml#L12). - -### Updating Go version - -We should always use a [supported version](https://golang.org/doc/devel/release#policy) -of Go, that is, one of the three most recent minor releases, and should always use -the most recent patch-level for that version, as it may contain security fixes. - -Changing the version affects every project being compiled, so it's important to -ensure that all projects have been updated to test against the new Go version -before changing the package builders to use it. Despite [Go's compatibility promise](https://golang.org/doc/go1compat), -changes between minor versions can expose bugs or cause problems in our projects. - -Once you've picked a new Go version to use, the steps to update Omnibus and CNG -are: - -- [Create a merge request in the CNG project](https://gitlab.com/gitlab-org/build/CNG/-/edit/master/ci_files/variables.yml?branch_name=update-go-version), - update the `GO_VERSION` in `ci_files/variables.yml`. -- [Create a merge request in the `gitlab-omnibus-builder` project](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/edit/master/docker/VERSIONS?branch_name=update-go-version), - update the `GO_VERSION` in `docker/VERSIONS`. -- Tag a new release of `gitlab-omnibus-builder` containing the change. -- [Create a merge request in the `omnibus-gitlab` project](https://gitlab.com/gitlab-org/omnibus-gitlab/edit/master/.gitlab-ci.yml?branch_name=update-gitlab-omnibus-builder-version), - update the `BUILDER_IMAGE_REVISION` to match the newly-created tag. - -To reduce unnecessary differences between two distribution methods, Omnibus and -CNG **should always use the same Go version**. - -### Supporting multiple Go versions - -Individual Golang-projects need to support multiple Go versions for the following reasons: - -1. When a new Go release is out, we should start integrating it into the CI pipelines to verify compatibility with the new compiler. -1. We must support the [Omnibus official Go version](#updating-go-version), which may be behind the latest minor release. -1. When Omnibus switches Go version, we still may need to support the old one for security backports. - -These 3 requirements may easily be satisfied by keeping support for the 3 latest minor versions of Go. - -It's ok to drop support for the oldest Go version and support only 2 latest releases, -if this is enough to support backports to the last 3 GitLab minor releases. - -Example: - -In case we want to drop support for `go 1.11` in GitLab `12.10`, we need to verify which Go versions we are using in `12.9`, `12.8`, and `12.7`. - -We do not consider the active milestone, `12.10`, because a backport for `12.7` is required in case of a critical security release. - -1. If both [Omnibus and CNG](#updating-go-version) were using Go `1.12` in GitLab `12.7` and later, then we safely drop support for `1.11`. -1. If Omnibus or CNG were using `1.11` in GitLab `12.7`, then we still need to keep support for Go `1.11` for easier backporting of security fixes. - ## Secure Team standards and style guidelines The following are some style guidelines that are specific to the Secure Team. |