Order branches according to OpenStack release names

OpenStack has changed the naming scheme for stable branches after
reaching the end of the alphabet. In order to make sure that the new
branches like stable/2023.1 are sorted after the previous names like
stable/zed, two new variables are introduced that control the sorting
behaviour.

Change-Id: I489dd7a811ebd09c16ecb1f85a0a2e162146962a

releasenotes/notes/openstack-stable-ordering-f5fd8801e105f13a.yaml

@@ -0,0 +1,16 @@
+---
+features:
+  - |
+    The default sort order for branch names has been modified in order
+    to accomodate the way OpenStack stable branches are named. Branches
+    that match the pattern ``stable/[0-9].*`` will be sorted as
+    ``stable/zzz[0-9].*``. This ensures that the new numerical branch
+    names like ``stable/2023.1`` will be sorted after the older stable
+    branches like ``stable/zed``. Two new variables have been added to
+    control the behaviour, ``branch_sort_re`` and ``branch_sort_prefix``.
+    See their help text for more information.
+upgrade:
+  - |
+    The default sort order for branch names has been modified in order
+    to accomodate the way OpenStack stable branches are named. See the
+    "Features" section for more information.

reno/config.py

@@ -133,6 +133,23 @@ _OPTIONS = [
         to "stable/".
         """)),
 
+    Opt('branch_sort_re', 'stable/([0-9].*)',
+        textwrap.dedent("""\
+        By default branches are sorted alphabetically, except
+        for branches matching this pattern, those will be sorted
+        with branch_sort_prefix inserted in order to accomodate
+        the way OpenStack stable branches are named and sorted.
+        """)),
+
+    Opt('branch_sort_prefix', 'stable/zzz',
+        textwrap.dedent("""\
+        The prefix to add to names of branches matched
+        by branch_sort_re. This allows OpenStack branches
+        to be sorted according to the current release
+        naming scheme. Set to "stable/" in order to
+        restore plain alphabetic ordering.
+        """)),
+
     Opt('sections',
         [
             ['features', 'New Features'],

reno/scanner.py

@@ -527,6 +527,11 @@ class Scanner(object):
             self.conf.closed_branch_tag_re,
             flags=re.VERBOSE | re.UNICODE,
         )
+        self.branch_sort_prefix = self.conf.branch_sort_prefix
+        self.branch_sort_re = re.compile(
+            self.conf.branch_sort_re,
+            flags=re.VERBOSE | re.UNICODE,
+        )
         self._ignore_uids = set(
             _get_unique_id(fn)
             for fn in self.conf.ignore_notes
@@ -842,6 +847,12 @@ class Scanner(object):
         return bool(self.get_file_at_commit(filename, sha,
                                             encoding=self._encoding))
 
+    def _branch_sort_key(self, name):
+        match = self.branch_sort_re.search(name)
+        if match:
+            return self.branch_sort_prefix + match.group(1)
+        return name
+
     def get_series_branches(self):
         "Get branches matching the branch_name_re config option."
         refs = self._repo.get_refs()
@@ -868,7 +879,7 @@ class Scanner(object):
                 LOG.debug('closed branch tag %s becomes %s',
                           r.rpartition('/')[-1], name)
                 branch_names.add(name)
-        return list(sorted(branch_names))
+        return list(sorted(branch_names, key=self._branch_sort_key))
 
     def _get_earlier_branch(self, branch):
         "Return the name of the branch created before the given branch."