--- stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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](https://semver.org/)], 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](https://gitlab.com/gitlab-org/build/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`](https://gitlab.com/gitlab-org/build/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](../build/team_member_docs.md#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`](https://gitlab.com/gitlab-org/omnibus-gitlab) repository. Create a new branch from the target branch (usually `master` of the [`gitlab-org/omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) repository. ### Modify `config/software/` 1. Find the corresponding configure file for the component that you want to update in the `config/software` directory. For example `config/software/prometheus.rb` is used for the Prometheus component. 1. 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/`. They are then referenced in the corresponding `config/software/.rb` file. Examples can be found at: - [unzip component](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/config/software/unzip.rb) - [unzip patches](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/config/patches/unzip). ### 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](../build/build_package.md). 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 manual `qa-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: ```plaintext upgrade--testplan.md ``` And add a link in `test-plans/index.md`.