add earliest_version option to scanner

Add an option to the scanner to tell it not to include all of the
history, but to stop at a specific version (inclusive). This will allow
us to configure release series history pages to only show versions that
are part of that series (otherwise, scanning stable/newton will include
mitaka releases from the master branch, for example).

Change-Id: I53b4b95e13c99d0a19f53e2f3e836ffe67428211
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/sphinxext.rst

@@ -52,6 +52,13 @@ Enable the extension by adding ``'reno.sphinxext'`` to the
      should be incorporated into the notes for the final release,
      after the final release is tagged.
 
+   *earliest-version*
+
+     A string containing the version number of the earliest version to
+     be included. For example, when scanning a branch, this is
+     typically set to the version used to create the branch to limit
+     the output to only versions on that branch.
+
 Examples
 ========
 

reno/lister.py

@@ -29,6 +29,7 @@ def list_cmd(args):
     notes = scanner.get_notes_by_version(
         reporoot, notesdir, args.branch,
         collapse_pre_releases=collapse,
+        earliest_version=args.earliest_version,
     )
     if args.version:
         versions = args.version

reno/main.py

@@ -82,6 +82,11 @@ def main(argv=sys.argv[1:]):
         default=False,
         help='combine pre-releases with their final release',
     )
+    do_list.add_argument(
+        '--earliest-version',
+        default=None,
+        help='stop when this version is reached in the history',
+    )
     do_list.set_defaults(func=lister.list_cmd)
 
     do_report = subparsers.add_parser(
@@ -114,6 +119,11 @@ def main(argv=sys.argv[1:]):
         default=False,
         help='combine pre-releases with their final release',
     )
+    do_report.add_argument(
+        '--earliest-version',
+        default=None,
+        help='stop when this version is reached in the history',
+    )
     do_report.set_defaults(func=report.report_cmd)
 
     args = parser.parse_args()

reno/report.py

@@ -25,6 +25,7 @@ def report_cmd(args):
     notes = scanner.get_notes_by_version(
         reporoot, notesdir, args.branch,
         collapse_pre_releases=collapse,
+        earliest_version=args.earliest_version,
     )
     if args.version:
         versions = args.version

reno/scanner.py

@@ -150,7 +150,8 @@ def _get_version_tags_on_branch(reporoot, branch):
 
 
 def get_notes_by_version(reporoot, notesdir, branch=None,
-                         collapse_pre_releases=False):
+                         collapse_pre_releases=False,
+                         earliest_version=None):
     """Return an OrderedDict mapping versions to lists of notes files.
 
     The versions are presented in reverse chronological order.
@@ -337,6 +338,10 @@ def get_notes_by_version(reporoot, notesdir, branch=None,
         # same order, but it doesn't really matter what order that is,
         # so just sort based on the unique id.
         trimmed[ov] = sorted(files_and_tags[ov])
+        # If we have been told to stop at a version, we can do that
+        # now.
+        if earliest_version and ov == earliest_version:
+            break
 
     LOG.debug('[reno] found %d versions and %d files',
               len(trimmed.keys()), sum(len(ov) for ov in trimmed.values()))

reno/sphinxext.py

@@ -34,6 +34,7 @@ class ReleaseNotesDirective(rst.Directive):
         'notesdir': directives.unchanged,
         'version': directives.unchanged,
         'collapse-pre-releases': directives.flag,
+        'earliest-version': directives.unchanged,
     }
 
     def run(self):
@@ -52,6 +53,7 @@ class ReleaseNotesDirective(rst.Directive):
         notessubdir = self.options.get('notesdir', defaults.NOTES_SUBDIR)
         version_opt = self.options.get('version')
         collapse = self.options.get('collapse-pre-releases')
+        earliest_version = self.options.get('earliest-version')
 
         notesdir = os.path.join(relnotessubdir, notessubdir)
         info('scanning %s for %s release notes' %
@@ -60,6 +62,7 @@ class ReleaseNotesDirective(rst.Directive):
         notes = scanner.get_notes_by_version(
             reporoot, notesdir, branch,
             collapse_pre_releases=collapse,
+            earliest_version=earliest_version,
         )
         if version_opt is not None:
             versions = [

reno/tests/test_scanner.py

@@ -459,6 +459,30 @@ class BasicTest(Base):
             results,
         )
 
+    def test_limit_by_earliest_version(self):
+        self._make_python_package()
+        self._add_notes_file()
+        self._run_git('tag', '-s', '-m', 'first tag', '1.0.0')
+        f2 = self._add_notes_file()
+        self._run_git('tag', '-s', '-m', 'middle tag', '2.0.0')
+        f3 = self._add_notes_file()
+        self._run_git('tag', '-s', '-m', 'last tag', '3.0.0')
+        raw_results = scanner.get_notes_by_version(
+            self.reporoot,
+            'releasenotes/notes',
+            earliest_version='2.0.0',
+        )
+        results = {
+            k: [f for (f, n) in v]
+            for (k, v) in raw_results.items()
+        }
+        self.assertEqual(
+            {'2.0.0': [f2],
+             '3.0.0': [f3],
+             },
+            results,
+        )
+
 
 class PreReleaseTest(Base):