Add method to find the next branch introducing breaking changes

If there is a last tag, use that as a base, otherwise use the current
branch as a base. If none is available, return `None`. If there is
a base, the major is incremented by one and the minor is set to `None`,
unless the major is 0 (an "initial development version" for semver), in
which case the major is set to 0 and the minor is incremented by one, as
the next minor could be a breaking change. Technically semver allows
breaking changes in patches for major version 0, but we assume patches
maintain backwards compatibility.

For example:

- `v0.x.x` -> `v0.2.x` (if the last tag is `v0.1.1` for example)
- `v0.2.x` -> `v0.3.x`
- `v1.x.x` -> `v2.x.x`
- `v1.0.x` -> `v2.x.x`
- `v0.0.1` -> `v0.1.x`
- `v0.3.1-pre.1+build.3` -> `v0.4.x`
- `v1.0.0` -> `v2.x.x`
- `v1.1.0` -> `v2.x.x`

This is useful to use as a maximum dependency version for a package.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/repo/config/version.py

@@ -347,6 +347,43 @@ def find_last_tag(self) -> semver.Version | None:
             return None
         return max(tags)
 
+    def find_next_breaking_branch(self) -> BranchVersion | None:
+        """Find the next branch potentially introducing breaking changes.
+
+        Returns:
+            If there is a last tag, use that as a base, otherwise use the current branch
+                as a base. If none is available, return `None`. If there is a base, the
+                major is incremented by one and the minor is set to `None`, unless the
+                major is 0 (an "initial development version" for semver), in which case
+                the major is set to 0 and the minor is incremented by one, as the next
+                minor could be a breaking change. Technically semver allows breaking
+                changes in patches for major version 0, but we assume patches maintain
+                backwards compatibility.
+        """
+        v_prefix = "v" if self._ref_name.startswith("v") else ""
+        last_tag = self.find_last_tag()
+        if last_tag is None:
+            branch = self.current_branch
+            if branch is None:
+                _logger.warning(
+                    "Trying to get the next breaking branch but there is no (valid) "
+                    "last tag nor current branch for %r",
+                    self._ref,
+                )
+                return None
+            major = branch.major + 1
+            minor = branch.minor or 1
+        else:
+            major = last_tag.major + 1
+            minor = last_tag.minor + 1
+
+        # If the next major is 1, then the current is 0, so the next minor could be
+        # a breaking change.
+        if major == 1:
+            return BranchVersion(major=0, minor=minor, name=f"{v_prefix}0.{minor}.x")
+
+        return BranchVersion(major=major, name=f"{v_prefix}{major}.x.x")
+
     def find_next_minor_for_major_branch(self) -> int | None:
         """Find the next minor version for the current major branch.
 

tests/test_version.py

@@ -182,6 +182,7 @@ class _Expected:  # pylint: disable=too-many-instance-attributes
     is_branch: bool = False
     is_branch_latest: bool = False
     next_minor_for_major_branch: int | None = None
+    next_breaking_branch: BranchVersion | None = None
 
 
 @dataclasses.dataclass(frozen=True, kw_only=True)
@@ -214,6 +215,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 0, 1),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -226,6 +228,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 1, 0),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -238,6 +241,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=False,
             last_tag=semver.Version(2, 0, 1),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -252,6 +256,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(3, 0, 0),
+            next_breaking_branch=BranchVersion(major=4, name="v4.x.x"),
         ),
     ),
     _TestCase(
@@ -265,6 +270,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(2, 1, 0),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -279,6 +285,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(2, 1, 1),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -291,6 +298,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             current_tag=semver.Version(1, 0, 2, "alpha.1"),
             is_tag=True,
             last_tag=semver.Version(1, 0, 2, "alpha.1"),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -304,6 +312,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 1, 0, "beta"),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -318,6 +327,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(3, 0, 0, "rc1"),
+            next_breaking_branch=BranchVersion(major=4, name="v4.x.x"),
         ),
     ),
     _TestCase(
@@ -332,6 +342,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(2, 1, 0, "alpha.1"),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -346,6 +357,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag_last_minor_for_major=True,
             is_tag_latest=True,
             last_tag=semver.Version(2, 0, 1, "rc1"),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -368,6 +380,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_branch=True,
             next_minor_for_major_branch=1,
             last_tag=semver.Version(1, 1, 0, "rc"),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -379,6 +392,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             current_branch=BranchVersion(major=1, minor=0, name="v1.0.x"),
             is_branch=True,
             last_tag=semver.Version(1, 0, 2, "alpha.1"),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -392,6 +406,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 0, 0),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -405,6 +420,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 0, 2),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -417,6 +433,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             current_tag=semver.Version(2, 0, 1),
             is_tag=True,
             last_tag=semver.Version(2, 0, 1),
+            next_breaking_branch=BranchVersion(major=3, name="v3.x.x"),
         ),
     ),
     _TestCase(
@@ -431,6 +448,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_tag=True,
             is_tag_last_minor_for_major=True,
             last_tag=semver.Version(1, 0, 0),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -443,6 +461,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             current_branch=BranchVersion(major=1, minor=None, name="v1.x.x"),
             is_branch=True,
             next_minor_for_major_branch=0,
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -456,6 +475,7 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             is_branch=True,
             next_minor_for_major_branch=1,
             last_tag=semver.Version(1, 1, 0, "rc"),
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
         ),
     ),
     _TestCase(
@@ -469,6 +489,57 @@ class _TestCase:  # pylint: disable=too-many-instance-attributes
             current_branch=BranchVersion(major=1, minor=None, name="v1.x.x"),
             is_branch=True,
             next_minor_for_major_branch=0,
+            next_breaking_branch=BranchVersion(major=2, name="v2.x.x"),
+        ),
+    ),
+    _TestCase(
+        title="release-0-major-0-minor",
+        ref="refs/tags/v0.0.1",
+        expected=_Expected(
+            ref="refs/tags/v0.0.1",
+            ref_name="v0.0.1",
+            current_tag=semver.Version(0, 0, 1),
+            is_tag=True,
+            last_tag=semver.Version(0, 0, 1),
+            next_breaking_branch=BranchVersion(major=0, minor=1, name="v0.1.x"),
+        ),
+    ),
+    _TestCase(
+        title="prerelease-0-major-3-minor",
+        ref="refs/tags/v0.3.1-pre.1+build.3",
+        expected=_Expected(
+            ref="refs/tags/v0.3.1-pre.1+build.3",
+            ref_name="v0.3.1-pre.1+build.3",
+            current_tag=semver.Version(0, 3, 1, "pre.1", "build.3"),
+            is_tag=True,
+            is_tag_last_minor_for_major=True,
+            last_tag=semver.Version(0, 3, 1, "pre.1", "build.3"),
+            next_breaking_branch=BranchVersion(major=0, minor=4, name="v0.4.x"),
+        ),
+    ),
+    _TestCase(
+        title="branch-0-major",
+        ref="refs/heads/v0.x.x",
+        expected=_Expected(
+            ref="refs/heads/v0.x.x",
+            ref_name="v0.x.x",
+            current_branch=BranchVersion(major=0, name="v0.x.x"),
+            is_branch=True,
+            next_minor_for_major_branch=2,
+            last_tag=semver.Version(0, 1, 0),
+            next_breaking_branch=BranchVersion(major=0, minor=2, name="v0.2.x"),
+        ),
+    ),
+    _TestCase(
+        title="branch-0-major-with-minor",
+        ref="refs/heads/v0.0.x",
+        expected=_Expected(
+            ref="refs/heads/v0.0.x",
+            ref_name="v0.0.x",
+            current_branch=BranchVersion(major=0, minor=0, name="v0.0.x"),
+            is_branch=True,
+            last_tag=semver.Version(0, 0, 1),
+            next_breaking_branch=BranchVersion(major=0, minor=1, name="v0.1.x"),
         ),
     ),
 ]
@@ -513,3 +584,7 @@ def test_repo_version(
         last_tag = repo_version_info.find_last_tag()
         assert last_tag is not None
         assert last_tag == case.expected.last_tag
+    assert (
+        repo_version_info.find_next_breaking_branch()
+        == case.expected.next_breaking_branch
+    )