Define internal releases package notation

Context

&1373 (closed) aims to elevate the GitLab Dedicated remediation process to be at the same level as the patch release process. In case of a high-severity SIRT incident, a private package must be generated to remediate GitLab Dedicated, this package will only contain the security fix for the high-severity vulnerability and it is not disclosed to the public.

In previous SIRT incidents, the package used a self-managed version, generating a poor experience for customers because a version was skipped. The purpose of this issue is to design and agree on the internal releases package notation

Proposal: Define the internal release package notation

GitLab Dedicated uses the GitLab N-1 version, this means GitLab Dedicated tenants run the last patch of the previous minor version. For example, considering 17.3 is the current version, GitLab Dedicated will run the last patch of 17.2, at this moment it will be 17.2.7.

If an internal package is required to be tagged:

  • It will be based on 17.2.7, e.g. 17.2.7-internal
  • On the next patch release, 17.2.8 will be tagged.

Alternatives for the internal release package notation could be:

  • 17.2.7-internal
  • 17.2.7-rc42
  • 17.2.7-ir - ir = internal release
  • 17.2.7-ip - ip = internal package
  • 17.2.7-pp - pp = private package
  • Other?

Status

2024-09-20

From the discussion in the issue's comments, at this moment, we prefer this notation: <major>.<minor>.<patch>-internal.<internal-version> . for example 17.3.3-internal.1 . This notions satisfies our requirements:

  • Inform the relation with the patch release version that is going to be released after this internal release, e.g. 17.3.3 will be released after 17.3.3-internal.1
  • Use - to indicate the release type
  • internal is clear and self-descriptive
  • There can be more than one internal release between two patch releases. .1 informs the numbering of the internal release. E.g. After releasing 17.3.3 , we need to make an urgent internal release and name it 17.3.3-internal.0 . After that, another internal release is needed, so it's named 17.3.3-internal.1 . The patch release after these 2 internal releases is 17.3.3 .
2024-10-01

From a feedback from Dedicated team:

So I'm coming around to the idea of accepting an extended (but not full) semver format. X.Y.Z-[a-z0-9]+ would allow the suffix to be -internal, -rc42 [...] What we should avoid is more dots in the suffix, because we use the number of dots to identify the X.Y.Z vs X.Y.202211240820-5f3539354de.75a10ecec64 formats, which need different constructions for package + image names.

We remove the dot . between internal and the internal version number from the previous proposal, so:

  • Old: <major>.<minor>.<patch>-internal.<internal-version> , e.g. 17.3.4-internal-1
  • New: <major>.<minor>.<patch>-internal<internal-version> , e.g. 17.3.4-internal1
2024-10-02

With more discussion, at the moment we have two possible options:

  1. Tag a new package using the new notation (#20501 (closed))
  2. We use release candidates for internal releases.

If we go with 2), then this issue may not be needed. However, if we go with 1), then the chosen tag notation is still <major>.<minor>.<patch>-internal<internal-version> , e.g. 17.3.4-internal1.

2024-10-15/Current decision

From a feedback from Distribution team, the package management tool dpkg understand 17.3.5+internal0.ee.0 as the newer version of 17.3.5. Thus, the internal release version must go off from the previous version:

Naming convention Example
Previous patch release

<major>.<minor>.<patch>

 17.5.1
Internal release

<major>.<minor>.<patch>-internal<internal-version>

17.5.1-internal0

17.5.1-internal1
Next patch release

<major>.<minor>.<patch+1>

 17.5.2

Git Diagram

%%{
    init:
    {
        'theme': 'base',
        'gitGraph':
        {
            "mainBranchName": 'security/17-3-stable'
        }
    }
}%%
gitGraph
    commit id: "Version v17.3.2" tag: "v17.3.2"
    commit id: "bug fix 1"
    commit id: "bug fix 2"
    branch critical-fix-1
    checkout critical-fix-1
    commit id: "critical fix 1"
    checkout security/17-3-stable
    merge critical-fix-1 tag: "v17.3.2-internal.0"
    commit id: "bug fix 3"
    branch critical-fix-2
    checkout critical-fix-2
    commit id: "critical fix 2"
    checkout security/17-3-stable
    merge critical-fix-2 tag: "v17.3.2-internal.1"
    commit id: "bug fix 4"
    commit id: "bug fix 5"
    commit id: "Version v17.3.3" tag: "v17.3.3"

Exit criteria

  • The notation should not impact GitLab self-managed versioning.
  • The notation does not create the impression of an unfinished / not fully tested product
Edited by Dat Tang