linters: add check_sru_version_string_convention

Add a check for expected version string for SRUs, using the conventions
documented in the project docs.

There is room for future improvement, most notably for native packages,
which are not supported by the check at all right now. This is just a
time restriction at the present moment, and should be implemented in the
future.

This is off for devel and a failure for stable by default.

Author: enr0n

tests/test_linters.py

@@ -250,3 +250,152 @@ def test_check_sru_version_string_breaks_upgrades(requests_mock):
         ubuntu_lint.check_sru_version_string_breaks_upgrades(
             ubuntu_lint.Context(changes=changes_bad_version)
         )
+
+
+def test_check_sru_version_string_convention(requests_mock):
+    changelog_tmpl = """hello ({next_version}) noble; urgency=medium
+
+  * Fix a bug (LP: #12345678)
+
+ -- John Doe <john.doe@example.com>  Wed, 11 Mar 2026 16:01:41 -0400
+
+hello ({prev_version}) noble; urgency=high
+
+  * No change rebuild for 64-bit time_t and frame pointers.
+
+ -- John Doe <john.doe@example.com>  Mon, 08 Apr 2024 17:58:52 +0200
+"""
+
+    rmadison_tmpls = [
+        textwrap.dedent(
+            """hello | 2.8-4         | trusty          | source
+               hello | 2.10-1        | xenial          | source
+               hello | 2.10-1build1  | bionic          | source
+               hello | 2.10-1build3  | bionic-security | source
+               hello | 2.10-1build3  | bionic-updates  | source
+               hello | 2.10-2ubuntu2 | focal           | source
+               hello | 2.10-2ubuntu4 | jammy           | source
+               hello | {prev_version}| noble           | source
+               hello | 2.10-5        | questing        | source
+               hello | 2.10-5build1  | resolute        | source
+        """),
+        # Same version in two releases
+        textwrap.dedent(
+            """hello | 2.8-4         | trusty          | source
+               hello | 2.10-1        | xenial          | source
+               hello | 2.10-1build1  | bionic          | source
+               hello | 2.10-1build3  | bionic-security | source
+               hello | 2.10-1build3  | bionic-updates  | source
+               hello | 2.10-2ubuntu2 | focal           | source
+               hello | 2.10-2ubuntu4 | jammy           | source
+               hello | {prev_version}| noble           | source
+               hello | {prev_version}| questing        | source
+               hello | 2.10-5build1  | resolute        | source
+        """),
+    ]
+
+    # (prev_version, next_version, expect_pass)
+    testcases_list = [
+        [
+            # 2.10-3 -> "2.10-3ubuntu0.1"
+            ("2.10-3", "2.10-3ubuntu0.1", True),
+            ("2.10-3", "2.10-3ubuntu1", False),
+            ("2.10-3", "2.10-4", False),
+            # 2.10-3ubuntu0.1 -> "2.10-3ubuntu0.2"
+            ("2.10-3ubuntu0.1", "2.10-3ubuntu0.2", True),
+            ("2.10-3ubuntu0.1", "2.10-3ubuntu1", False),
+            # 2.10-3ubuntu2 -> "2.10-3ubuntu2.1"
+            ("2.10-3ubuntu2", "2.10-3ubuntu2.1", True),
+            ("2.10-3ubuntu2", "2.10-3ubuntu3", False),
+            # 2.10-3ubuntu2.1 -> "2.10-3ubuntu2.2"
+            ("2.10-3ubuntu2.1", "2.10-3ubuntu2.2", True),
+            ("2.10-3ubuntu2.1", "2.10-3ubuntu3", False),
+            # 2.10-3build1 -> 2.10-3ubuntu0.1
+            ("2.10-3build1", "2.10-3ubuntu0.1", True),
+            ("2.10-3build1", "2.10-3build2", False),
+            ("2.10-3build1", "2.10-3ubuntu1", False),
+            # 2.10-3ubuntu0.24.04.1 -> 2.10-3ubuntu0.24.04.2
+            ("2.10-3ubuntu0.24.04.1", "2.10-3ubuntu0.24.04.2", True),
+            ("2.10-3ubuntu0.24.04.1", "2.10-3ubuntu1", False),
+        ],
+        [
+            # 2.10-5 in two releases -> 2.10-5ubuntu0.24.04.1
+            ("2.10-5", "2.10-5ubuntu0.24.04.1", True),
+            ("2.10-5", "2.10-5ubuntu0.1", False),
+            ("2.10-5", "2.10-5ubuntu1", False),
+            ("2.10-5", "2.10-6", False),
+            # 2.10-5build1 in two releases -> 2.10-5ubuntu0.24.04.1
+            ("2.10-5build1", "2.10-5ubuntu0.24.04.1", True),
+            ("2.10-5build1", "2.10-5ubuntu0.1", False),
+            ("2.10-5build1", "2.10-5ubuntu1", False),
+            ("2.10-5build1", "2.10-5build2", False),
+            # 2.10-5ubuntu1 in two releases -> 2.10-5ubuntu1.24.04.1
+            ("2.10-5ubuntu1", "2.10-5ubuntu1.24.04.1", True),
+            ("2.10-5ubuntu1", "2.10-5ubuntu1.1", False),
+            ("2.10-5ubuntu1", "2.10-5ubuntu2", False),
+            # 2.10-5ubuntu1.1 in two releases -> 2.10-5ubuntu1.1.24.04.1
+            ("2.10-5ubuntu1.1", "2.10-5ubuntu1.1.24.04.1", True),
+            ("2.10-5ubuntu1.1", "2.10-5ubuntu1.2", False),
+            ("2.10-5ubuntu1.1", "2.10-5ubuntu2", False),
+        ],
+    ]
+
+    for i in range(len(testcases_list)):
+        rmadison_tmpl = rmadison_tmpls[i]
+        testcases = testcases_list[i]
+
+        for (prev_version, next_version, expect_pass) in testcases:
+            requests_mock.get(
+                "https://people.canonical.com/~ubuntu-archive/madison.cgi?package=hello&a=source&text=on",
+                text=rmadison_tmpl.format(prev_version=prev_version)
+            )
+            debian_changelog = changelog.Changelog(
+                changelog_tmpl.format(
+                    prev_version=prev_version,
+                    next_version=next_version,
+                )
+            )
+            context = ubuntu_lint.Context(debian_changelog=debian_changelog)
+
+            if expect_pass:
+                ubuntu_lint.check_sru_version_string_convention(context)
+            else:
+                with pytest.raises(
+                    ubuntu_lint.LintFailure,
+                    match=f"{next_version} does not match expected version"
+                ):
+                    ubuntu_lint.check_sru_version_string_convention(context)
+
+    # Test cases for new upstream version
+    testcases = [
+        # 2.10-3ubuntu1 -> 2.11-0ubuntu0.24.04.1 (new upstream)
+        ("2.10-3ubuntu1", "2.11-0ubuntu0.24.04.1", True),
+        ("2.10-3ubuntu1", "2.11-0ubuntu0.1", False),
+        # 2.10-3ubuntu1 -> 2.11-0ubuntu0~24.04.1 (new upstream)
+        ("2.10-3ubuntu1", "2.11-0ubuntu0~24.04.1", True),
+        # 2.10-3ubuntu1 -> 2.11-1ubuntu2~24.04.1 (devel backport)
+        ("2.10-3ubuntu1", "2.11-1ubuntu2~24.04.1", True),
+        ("2.10-3ubuntu1", "2.11-1ubuntu2", False),
+    ]
+
+    for (prev_version, next_version, expect_pass) in testcases:
+        requests_mock.get(
+            "https://people.canonical.com/~ubuntu-archive/madison.cgi?package=hello&a=source&text=on",
+            text=rmadison_tmpls[0].format(prev_version=prev_version)
+        )
+        debian_changelog = changelog.Changelog(
+            changelog_tmpl.format(
+                prev_version=prev_version,
+                next_version=next_version,
+            )
+        )
+        context = ubuntu_lint.Context(debian_changelog=debian_changelog)
+
+        if expect_pass:
+            ubuntu_lint.check_sru_version_string_convention(context)
+        else:
+            with pytest.raises(
+                ubuntu_lint.LintFailure,
+                match="version string for new upstream should contain suffix"
+            ):
+                ubuntu_lint.check_sru_version_string_convention(context)

ubuntu_lint/__init__.py

@@ -16,6 +16,7 @@
     check_sru_bug_missing_template,
     check_sru_bug_missing_release_tasks,
     check_sru_version_string_breaks_upgrades,
+    check_sru_version_string_convention,
 )
 
 __all__ = [
@@ -31,4 +32,5 @@
     "check_sru_bug_missing_template",
     "check_sru_bug_missing_release_tasks",
     "check_sru_version_string_breaks_upgrades",
+    "check_sru_version_string_convention",
 ]

ubuntu_lint/cli.py

@@ -19,6 +19,7 @@ class Runner:
         "sru-bug-missing-template": ubuntu_lint.check_sru_bug_missing_template,
         "sru-bug-missing-release-tasks": ubuntu_lint.check_sru_bug_missing_release_tasks,
         "sru-version-string-breaks-upgrades": ubuntu_lint.check_sru_version_string_breaks_upgrades,
+        "sru-version-string-convention": ubuntu_lint.check_sru_version_string_convention,
     }
 
     # Default actions when linting development release.
@@ -32,6 +33,7 @@ class Runner:
         "sru-bug-missing-template": "off",
         "sru-bug-missing-release-tasks": "off",
         "sru-version-string-breaks-upgrades": "off",
+        "sru-version-string-convention": "off",
     }
 
     # Default actions when linting stable releases.
@@ -45,6 +47,7 @@ class Runner:
         "sru-bug-missing-template": "warn",
         "sru-bug-missing-release-tasks": "warn",
         "sru-version-string-breaks-upgrades": "warn",
+        "sru-version-string-convention": "warn",
     }
 
     def __init__(self):

ubuntu_lint/linters.py

@@ -275,3 +275,90 @@ def check_sru_version_string_breaks_upgrades(context: Context):
                 f"{target_version} for {target_series} is greater than {v} for {s}, "
                 "which breaks the upgrade path"
             )
+
+
+def check_sru_version_string_convention(context: Context):
+    """
+    Examines the package version string to determine if it is appropriate for SRU.
+    """
+    docs = "https://documentation.ubuntu.com/project/how-ubuntu-is-made/concepts/version-strings"
+
+    next_version = context.changelog_entry.version
+    prev_version = context.changelog_entry_by_index(1).version
+
+    try:
+        if next_version.full_version != context.changes.get("Version"):
+            context.lint_fail("changes file version does not match changelog version")
+    except MissingContextException:
+        pass
+
+    match = re.search(r"-[0-9]*", prev_version.full_version)
+    if match:
+        (upstream_version, debian_revison, ubuntu_revision) = prev_version.full_version.partition(match.group())
+    else:
+        context.lint_fail(
+            "check not implemented for native packages, "
+            f"please check {docs} to ensure version string is correct"
+        )
+
+    dists = context.changelog_entry.distributions
+    if dists is not None:
+        series_version = distro_info.UbuntuDistroInfo().version(dists.partition('-')[0])
+        # Strip off " LTS" if needed.
+        series_version = series_version.partition(' ')[0]
+    else:
+        context.lint_fail("changelog entry is missing distribution field")
+
+    if debian_support.version_compare(next_version.upstream_version, prev_version.upstream_version) > 0:
+        # Handle new upstream version separately from the rest. This check could be
+        # expanded in the future to cover more cases, but at the very least, the new
+        # version should end in e.g. 24.04.1.
+        if not next_version.full_version.endswith(f"{series_version}.1"):
+            context.lint_fail(
+                f"version string for new upstream should contain suffix {series_version}.1"
+            )
+        return
+
+    # If the previous version is published across multiple series, then we expect e.g.
+    # ubuntu24.04.x suffixes.
+    max_version_by_series = _rmadision_get_max_version_by_series(context)
+    series_with_version = list(max_version_by_series.values()).count(prev_version)
+
+    if series_with_version < 1:
+        context.lint_fail("rmadison output is not consistent with changelog")
+
+    suffix_extra: str = ""
+    if series_with_version > 1:
+        suffix_extra = f".{series_version}"
+
+    expect: str = ""
+    if not ubuntu_revision:
+        # E.g. 2.0-1 -> 2.0-1ubuntu0.1
+        expect = f"{upstream_version}{debian_revison}ubuntu0{suffix_extra}.1"
+    elif "ubuntu" not in ubuntu_revision:
+        # E.g. 2.0-1build1 -> 2.0-1ubuntu0.1
+        expect = f"{upstream_version}{debian_revison}ubuntu0{suffix_extra}.1"
+    elif "." not in ubuntu_revision:
+        # E.g. 2.0-1ubuntu1 -> 2.0-1ubuntu1.1
+        expect = f"{str(prev_version)}{suffix_extra}.1"
+    elif suffix_extra:
+        # All other cases where there multiple series with the same version.
+        expect = f"{str(prev_version)}{suffix_extra}.1"
+    else:
+        # E.g. 2.0-1ubuntu1.1 -> 2.0-1ubuntu1.2
+        try:
+            parts = ubuntu_revision.split(".")
+            parts[-1] = str(int(parts[-1]) + 1)
+            new_ubuntu_revision = ".".join(parts)
+
+            expect = f"{upstream_version}{debian_revison}{new_ubuntu_revision}"
+        except ValueError:
+            context.lint_fail(
+                f"cannot handle version string format {prev_version}"
+            )
+
+    if next_version.full_version != expect:
+        context.lint_fail(
+            f"{next_version} does not match expected version {expect}, "
+            f"see {docs} for expected version string conventions"
+        )