Add support for patching history table

bump_definitions.py

@@ -27,13 +27,16 @@
 import time
 from pathlib import Path
 from typing import List
+from typing import Optional
 
 import semver
 
 import versions
 
 
-def _bump_versions(root: Path, position: str, pattern: str) -> List[Path]:
+def _bump_versions(
+    root: Path, position: str, pattern: str, history_entry: Optional[str] = None
+) -> List[Path]:
     """Find definition files in the given directory, match their types
     against the given glob pattern, and create new files with version
     bumps in the selected position. Return the paths of the created
@@ -48,18 +51,25 @@ def _bump_versions(root: Path, position: str, pattern: str) -> List[Path]:
         new_version = getattr(version, "bump_" + position)()
         new_path = old_path.with_name(f"{new_version}.yml")
         new_path.write_text(
-            _transform_definition(old_path.read_text(encoding="utf-8"), new_version),
+            _transform_definition(
+                old_path.read_text(encoding="utf-8"),
+                new_version,
+                history_entry=history_entry,
+            ),
             encoding="utf-8",
         )
         result.append(new_path)
     return result
 
 
 def _transform_definition(
-    old_definition: str, version: semver.version.Version, copyright_year: int = None
+    old_definition: str,
+    version: semver.version.Version,
+    history_entry: Optional[str] = None,
+    copyright_year: int = None,
 ) -> str:
     """Return an updated type definition with the new version and
-    copyright year patched in.
+    copyright year patched in, and a new entry in the history table.
     """
     result = re.sub(
         r"^_version: (.*)$", f"_version: {version}", old_definition, flags=re.M
@@ -85,6 +95,14 @@ def _transform_definition(
     ):
         result = re.sub(expr, repl, result, flags=re.M)
 
+    history_entry = history_entry or "PLEASE UPDATE"
+    result = re.sub(
+        r"^_history:$",
+        f"_history:\n  - version: {version}\n    changes: {history_entry}",
+        result,
+        flags=re.M,
+    )
+
     return result
 
 
@@ -101,6 +119,16 @@ def _transform_definition(
         metavar="TYPE_PATTERN",
         help="a glob pattern that selects which types should be bumped",
     )
+    argparser.add_argument(
+        "--history-entry",
+        metavar="TEXT",
+        help="the text that should be added to the new version's history table",
+    )
     args = argparser.parse_args(sys.argv[1:])
-    for path in _bump_versions(Path("definitions"), args.position, args.pattern):
+    for path in _bump_versions(
+        Path("definitions"),
+        args.position,
+        args.pattern,
+        history_entry=args.history_entry,
+    ):
         print(path)

test_bump_definitions.py

@@ -13,30 +13,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import re
+import textwrap
 
 import semver
 
 import bump_definitions
 
 
-def _strip_leading_indent(s):
-    return re.sub(r"^\s+", "", s, flags=re.M)
-
-
 def test_transform_definition_replaces_version():
     assert (
         bump_definitions._transform_definition(
-            _strip_leading_indent(
-                """
+            textwrap.dedent(
+                """\
                 # Copyright blah
                 _version: 1.0.0
                 """
             ),
             semver.VersionInfo.parse("2.0.0"),
         )
-        == _strip_leading_indent(
-            """
+        == textwrap.dedent(
+            """\
             # Copyright blah
             _version: 2.0.0
             """
@@ -47,16 +43,16 @@ def test_transform_definition_replaces_version():
 def test_transform_definition_updates_range():
     assert (
         bump_definitions._transform_definition(
-            _strip_leading_indent(
-                """
+            textwrap.dedent(
+                """\
                 # Copyright 2020-2021 Company Name, Inc.
                 """
             ),
             semver.VersionInfo.parse("2.0.0"),
             copyright_year=2025,
         )
-        == _strip_leading_indent(
-            """
+        == textwrap.dedent(
+            """\
             # Copyright 2020-2025 Company Name, Inc.
             """
         )
@@ -66,17 +62,68 @@ def test_transform_definition_updates_range():
 def test_transform_definition_turn_year_into_range():
     assert (
         bump_definitions._transform_definition(
-            _strip_leading_indent(
-                """
+            textwrap.dedent(
+                """\
                 # Copyright 2020 Company Name, Inc.
                 """
             ),
             semver.VersionInfo.parse("2.0.0"),
             copyright_year=2025,
         )
-        == _strip_leading_indent(
-            """
+        == textwrap.dedent(
+            """\
             # Copyright 2020-2025 Company Name, Inc.
             """
         )
     )
+
+
+def test_transform_definition_adds_history_entry_with_given_string():
+    assert (
+        bump_definitions._transform_definition(
+            textwrap.dedent(
+                """\
+                _history:
+                  - version: 1.0.0
+                    changes: foo
+                """
+            ),
+            semver.VersionInfo.parse("2.0.0"),
+            history_entry="things have changed",
+            copyright_year=2025,
+        )
+        == textwrap.dedent(
+            """\
+            _history:
+              - version: 2.0.0
+                changes: things have changed
+              - version: 1.0.0
+                changes: foo
+            """
+        )
+    )
+
+
+def test_transform_definition_adds_history_entry_with_default_string():
+    assert (
+        bump_definitions._transform_definition(
+            textwrap.dedent(
+                """\
+                _history:
+                  - version: 1.0.0
+                    changes: foo
+                """
+            ),
+            semver.VersionInfo.parse("2.0.0"),
+            copyright_year=2025,
+        )
+        == textwrap.dedent(
+            """\
+            _history:
+              - version: 2.0.0
+                changes: PLEASE UPDATE
+              - version: 1.0.0
+                changes: foo
+            """
+        )
+    )