Upgrading software components
The Linux package is created from a series of software components, some of which are developed by GitLab and others which are sourced from free and open source projects. Software components can be updated individually as new features, bug fixes, and security vulnerabilities become available.
Software component upgrades can be risky, especially when non-backwards compatible changes are made. Considering Semantic versioning], examining changelogs, and examining release notes can give a sense of the amount of risk involved in an upgrade. In all cases, upgrades should be thoroughly tested before merging.
The CNG project uses some of these same software components. Components common to both projects should be updated in both.
Types of software components
There are two types of software components used in the Linux package:
- External software components
- Internal software components
External software components
External software components source is downloaded directly from an external site
or copied from the
omnibus-mirror
repository.
A component can be provided using a git clone
, extracting from a source
tarball, performing a gem install
(for Ruby modules), or performing a pip
install
(for Python modules).
Internal software components
Internal software component are developed by GitLab and external contributors.
Source for internal software components is downloaded from a project’s GitLab
repository. Versions used in a build are set by the Git reference contained in
the project’s corresponding *VERSION
files. These versions can be overridden
by environment variables. For more information, see
Use specific branches or versions of a GitLab component.
Updates to internal software components are done by merge requests in the corresponding repository.
Internal software component update workflow
A typical workflow for updating an internal software component.
Create a fork/branch
External contributors should create a fork of the
gitlab-org/omnibus-gitlab
repository.
Create a new branch from the target branch (usually master
of the
gitlab-org/omnibus-gitlab
repository.
Modify config/software/<component.rb>
-
Find the corresponding configure file for the component that you want to update in the
config/software
directory. For exampleconfig/software/prometheus.rb
is used for the Prometheus component. -
Change the version to the version you want to update to. If applicable, also change the corresponding
sha256
to the value of the corresponding version source tarball.
Add or modify any required patches
The new component version may require:
- Adding new patches.
- Removing existing patches.
- Changing existing patches.
All patch files go in config/patches/<component name>
. They are then
referenced in the corresponding config/software/<component name>.rb
file.
Examples can be found at:
Push branch
Push the branch to the to the upstream repository.
Create merge request (MR)
Create a merge request using your development branch and the target branch.
Build
Build the Linux package either:
- Using the CI/CD system.
- Building locally using Build local Linux package.
You must build on all architectures using the CI/CD system before a merge request for an updated software component can be accepted.
Test
Install the resulting Linux package and test the component changes.
Testing software component updates
Minimum test requirements
At a minimum, the following tests should be performed when updating a software component.
- Perform a successful GitLab Enterprise Edition (EE) build on all supported platforms.
- Run
qa-subset-test
as well as manualqa-remaining-test-manual
CI/CD test job for both GitLab Enterprise Edition and GitLab Community Edition. - Install and verify that component version has been upgraded.
- Verify basic functionality of the software component.
Additional testing is almost always required and varies depending on the software component.
Test plans
Here are test plans for individual components. They are meant to be copied into the merge request where their execution can be recorded.
Not every component is listed here. Please consider creating a merge request to
add one for a component upgrade that you are working on. Use
test-plans/upgrade-component-testplan-template.md
as a starting point.
These test plans are not exhaustive. The might need to be supplemented depending on the degree of change made to the component. Record these additions in the merge request and consider adding them here. Use the following filename pattern when creating the test plan file:
upgrade-<component-name>-testplan.md
And add a link in test-plans/index.md
.