2019-05-24 04:03:22 -04:00
---
2022-05-29 20:08:35 -04:00
stage: Systems
2020-11-05 13:08:48 -05:00
group: Distribution
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-05-24 04:03:22 -04:00
type: concepts
---
2020-07-07 02:09:06 -04:00
# GitLab release and maintenance policy
2019-05-24 04:03:22 -04:00
GitLab has strict policies governing version naming, as well as release pace for major, minor,
2020-07-15 11:09:21 -04:00
patch, and security releases. New releases are announced on the [GitLab blog ](https://about.gitlab.com/releases/categories/releases/ ).
2017-10-11 09:01:55 -04:00
2019-12-30 13:09:23 -05:00
Our current policy is:
2020-06-05 17:08:27 -04:00
- Backporting bug fixes for **only the current stable release** at any given time. (See [patch releases ](#patch-releases ).)
2020-07-15 11:09:21 -04:00
- Backporting security fixes **to the previous two monthly releases in addition to the current stable release** . (See [security releases ](#security-releases ).)
In rare cases, release managers may make an exception and backport to more than
the last two monthly releases. See [Backporting to older
releases](#backporting-to-older-releases) for more information.
2019-12-30 13:09:23 -05:00
2017-10-11 09:01:55 -04:00
## Versioning
2019-07-08 20:20:40 -04:00
GitLab uses [Semantic Versioning ](https://semver.org/ ) for its releases:
2019-10-07 14:06:24 -04:00
`(Major).(Minor).(Patch)` .
2017-10-11 09:01:55 -04:00
2021-06-08 23:10:22 -04:00
For example, for GitLab version 13.10.6:
2017-10-11 09:01:55 -04:00
2021-06-08 23:10:22 -04:00
- `13` represents the major version. The major release was 13.0.0 but often referred to as 13.0.
- `10` represents the minor version. The minor release was 13.10.0 but often referred to as 13.10.
2020-06-05 17:08:27 -04:00
- `6` represents the patch number.
2019-01-22 20:32:38 -05:00
Any part of the version number can increment into multiple digits, for example, 13.10.11.
2019-01-17 22:34:18 -05:00
2019-01-18 14:23:31 -05:00
The following table describes the version types and their release cadence:
2019-01-17 22:34:18 -05:00
2019-05-24 04:03:22 -04:00
| Version type | Description | Cadence |
|:-------------|:------------|:--------|
2021-10-13 02:11:33 -04:00
| Major | For significant changes, or when any backward-incompatible changes are introduced to the public API. | Yearly. The next major release is GitLab 15.0 on May 22, 2022. GitLab schedules major releases on May 22 each year, by default. |
2019-01-18 14:23:31 -05:00
| Minor | For when new backward-compatible functionality is introduced to the public API, a minor feature is introduced, or when a set of smaller features is rolled out. | Monthly on the 22nd. |
| Patch | For backward-compatible bug fixes that fix incorrect behavior. See [Patch releases ](#patch-releases ). | As needed. |
2017-10-11 09:01:55 -04:00
2020-06-05 17:08:27 -04:00
## Upgrade recommendations
We encourage everyone to run the [latest stable release ](https://about.gitlab.com/releases/categories/releases/ )
to ensure that you can easily upgrade to the most secure and feature-rich GitLab experience.
2020-07-07 11:08:49 -04:00
To make sure you can easily run the most recent stable release, we are working
2020-06-05 17:08:27 -04:00
hard to keep the update process simple and reliable.
If you are unable to follow our monthly release cycle, there are a couple of
2021-12-10 07:10:18 -05:00
cases you need to consider. Follow the
[upgrade paths guide ](../update/index.md#upgrade-paths ) to safely upgrade
between versions.
2020-06-05 17:08:27 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2021-09-15 14:11:29 -04:00
Version specific changes in Omnibus GitLab Linux packages can be found in [the Omnibus GitLab documentation ](../update/package/index.md#version-specific-changes ).
2020-06-05 17:08:27 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2021-09-15 14:11:29 -04:00
Instructions are available for downloading an Omnibus GitLab Linux package locally and [manually installing ](../update/package/index.md#upgrade-using-a-manually-downloaded-package ) it.
2020-06-05 17:08:27 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2020-09-03 11:08:29 -04:00
A step-by-step guide to [upgrading the Omnibus-bundled PostgreSQL is documented separately ](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server ).
2020-11-05 13:08:48 -05:00
## Upgrading major versions
2020-06-05 17:08:27 -04:00
2021-02-11 04:09:18 -05:00
Backward-incompatible changes and migrations are reserved for major versions. See the [upgrade guide ](../update/index.md#upgrading-to-a-new-major-version ).
2020-11-02 13:09:03 -05:00
2017-10-31 12:05:06 -04:00
## Patch releases
2017-10-11 09:01:55 -04:00
2019-11-04 07:06:19 -05:00
Patch releases **only include bug fixes** for the current stable released version of
GitLab.
These two policies are in place because:
1. GitLab has Community and Enterprise distributions, doubling the amount of work
necessary to test/release the software.
1. Backporting to more than one release creates a high development, quality assurance,
and support cost.
1. Supporting parallel version discourages incremental upgrades which over time accumulate in
complexity and create upgrade challenges for all users. GitLab has a dedicated team ensuring that
incremental upgrades (and installations) are as simple as possible.
2020-07-07 11:08:49 -04:00
1. The number of changes created in the GitLab application is high, which contributes to backporting complexity to older releases. In several cases, backporting has to go through the same
2019-11-04 07:06:19 -05:00
review process a new change goes through.
2020-07-07 11:08:49 -04:00
1. Ensuring that tests pass on the older release is a considerable challenge in some cases, and as such is very time-consuming.
2019-11-04 07:06:19 -05:00
2020-07-07 11:08:49 -04:00
Including new features in a patch release is not possible as that would break [Semantic Versioning ](https://semver.org/ ).
2019-11-26 07:06:18 -05:00
Breaking [Semantic Versioning ](https://semver.org/ ) has the following consequences for users that
2019-12-10 22:07:31 -05:00
have to adhere to various internal requirements (for example, org. compliance, verifying new features, and similar):
2019-11-04 07:06:19 -05:00
1. Inability to quickly upgrade to leverage bug fixes included in patch versions.
1. Inability to quickly upgrade to leverage security fixes included in patch versions.
1. Requirements consisting of extensive testing for not only stable GitLab release, but every patch version.
In cases where a strategic user has a requirement to test a feature before it is
2021-04-25 20:09:41 -04:00
officially released, we can offer to create a Release Candidate (RC) version that
includes the specific feature. This should be needed only in extreme cases and can be requested for
2020-05-29 11:08:14 -04:00
consideration by raising an issue in the [release/tasks ](https://gitlab.com/gitlab-org/release/tasks/-/issues/new?issuable_template=Backporting-request ) issue tracker.
2021-04-25 20:09:41 -04:00
It is important to note that the Release Candidate contains other features and changes as
2019-12-10 22:07:31 -05:00
it is not possible to easily isolate a specific feature (similar reasons as noted above). The
2021-04-25 20:09:41 -04:00
Release Candidate is no different than any code that is deployed to GitLab.com or is publicly
2019-12-10 22:07:31 -05:00
accessible.
2019-11-04 07:06:19 -05:00
### Backporting to older releases
2020-07-15 11:09:21 -04:00
Backporting to more than one stable release is normally reserved for [security releases ](#security-releases ).
2020-07-07 11:08:49 -04:00
In some cases, however, we may need to backport *a bug fix* to more than one stable
2017-10-31 12:05:06 -04:00
release, depending on the severity of the bug.
2017-10-11 09:01:55 -04:00
2019-12-10 22:07:31 -05:00
The decision on whether backporting a change will be performed is done at the discretion of the
[current release managers ](https://about.gitlab.com/community/release-managers/ ), similar to what is
2021-06-08 14:10:23 -04:00
described in the [managing bugs ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md#managing-bugs ) process,
2019-12-10 22:07:31 -05:00
based on *all* of the following:
2019-11-04 07:06:19 -05:00
2019-12-10 22:07:31 -05:00
1. Estimated [severity ](../development/contributing/issue_workflow.md#severity-labels ) of the bug:
Highest possible impact to users based on the current definition of severity.
1. Estimated [priority ](../development/contributing/issue_workflow.md#priority-labels ) of the bug:
Immediate impact on all impacted users based on the above estimated severity.
2019-11-04 07:06:19 -05:00
1. Potentially incurring data loss and/or security breach.
1. Potentially affecting one or more strategic accounts due to a proven inability by the user to upgrade to the current stable version.
If *all* of the above are satisfied, the backport releases can be created for
2020-07-15 11:09:21 -04:00
the current stable release, and two previous monthly releases. In rare cases a release manager may grant an exception to backport to more than two previous monthly releases.
2021-06-08 23:10:22 -04:00
For instance, if we release `13.2.1` with a fix for a severe bug introduced in
`13.0.0` , we could backport the fix to a new `13.0.x` , and `13.1.x` patch release.
2019-11-04 07:06:19 -05:00
2022-05-17 05:08:20 -04:00
Note that [severity ](../development/contributing/issue_workflow.md#severity-labels ) 3 and lower
requests will be automatically turned down.
2022-05-16 11:08:39 -04:00
2019-12-10 22:07:31 -05:00
To request backporting to more than one stable release for consideration, raise an issue in the
2020-05-29 11:08:14 -04:00
[release/tasks ](https://gitlab.com/gitlab-org/release/tasks/-/issues/new?issuable_template=Backporting-request ) issue tracker.
2017-10-11 09:01:55 -04:00
2017-10-31 12:05:06 -04:00
### Security releases
Security releases are a special kind of patch release that only include security
2019-12-30 13:09:23 -05:00
fixes and patches (see below) for the previous two monthly releases in addition to the current stable release.
2017-10-11 09:01:55 -04:00
2017-10-31 12:05:06 -04:00
For very serious security issues, there is
2020-03-22 23:09:21 -04:00
[precedent ](https://about.gitlab.com/releases/2016/05/02/cve-2016-4340-patches/ )
2017-10-31 12:05:06 -04:00
to backport security fixes to even more monthly releases of GitLab.
This decision is made on a case-by-case basis.
2017-10-11 09:01:55 -04:00
2020-03-17 23:09:43 -04:00
## More information
2017-10-11 09:01:55 -04:00
2021-06-02 14:10:01 -04:00
You may also want to read our:
- [Release documentation ](https://gitlab.com/gitlab-org/release/docs ) describing release procedures
- [Deprecation guidelines ](../development/deprecation_guidelines/index.md )
- [Responsible Disclosure Policy ](https://about.gitlab.com/security/disclosure/ )
