CLOUDP-295785 - Calculate next version and release notes script (#193)

# Summary

Initial work for calculating next operator version and release notes.
This is based on
https://docs.google.com/document/d/1eJ8iKsI0libbpcJakGjxcPfbrTn8lmcZDbQH1UqMR_g/edit?tab=t.aov8hxoyxtos#heading=h.6q8mwv95pdu6.

**This is not yet integrated with CI nor forces engineers to create
change log files. There will be next smaller PRs that will address
missing integration. Functionalities added by this PR:**

1. `scripts.release.calculate_next_version.py` -> this will calculate
next version based on the changelog files provided.
```sh
➜  mongodb-kubernetes ✗ python3 -m scripts.release.calculate_next_version --help
usage: calculate_next_version.py [-h] [-p ] [-c ] [-s ] [-v ]

Calculate the next version based on the changes since the previous version tag.

options:
  -h, --help            show this help message and exit
  -p, --path            Path to the Git repository. Default is the current directory '.'
  -c, --changelog-path
                        Path to the changelog directory relative to the repository root. Default is 'changelog/'
  -s, --initial-commit-sha
                        SHA of the initial commit to start from if no previous version tag is found.
  -v, --initial-version
                        Version to use if no previous version tag is found. Default is '1.0.0'
```

2. `scripts.release.create_changelog.py` -> this is a tool for creating
changelog files. It makes life easier for engineers and reduces a chance
for errors in filename and contents syntax
```sh
➜  mongodb-kubernetes ✗python3 -m scripts.release.create_changelog --help
usage: create_changelog.py [-h] [-c ] [-d ] [-e] -k  title

Utility to easily create a new changelog entry file.

positional arguments:
  title                 Title for the changelog entry

options:
  -h, --help            show this help message and exit
  -c, --changelog-path
                        Path to the changelog directory relative to a current working directory. Default is 'changelog/'
  -d, --date            Date in 'YYYY-MM-DD' format to use for the changelog entry. Default is today's date
  -e, --editor          Open the created changelog entry in the default editor (if set, otherwise uses 'vi'). Default is True
  -k, --kind            Kind of the changelog entry:
                          - 'prelude' for prelude entries
                          - 'breaking' for breaking change entries
                          - 'feature' for feature entries
                          - 'fix' for bugfix entries
                          - 'other' for other entries
```

3. `scripts.release.release_notes.py` -> create release notes based on
the changes since last release tag
```sh
➜  mongodb-kubernetes ✗ python3 -m scripts.release.release_notes --help
usage: release_notes.py [-h] [-p ] [-c ] [-s ] [-v ] [--output ]

Generate release notes based on the changes since the previous version tag.

options:
  -h, --help            show this help message and exit
  -p, --path            Path to the Git repository. Default is the current directory '.'
  -c, --changelog-path
                        Path to the changelog directory relative to the repository root. Default is 'changelog/'
  -s, --initial-commit-sha
                        SHA of the initial commit to start from if no previous version tag is found.
  -v, --initial-version
                        Version to use if no previous version tag is found. Default is '1.0.0'
  --output, -o          Path to save the release notes. If not provided, prints to stdout.
```

## Proof of Work

Passing unit tests for now is enough.

## Checklist
- [x] Have you linked a jira ticket and/or is the ticket in the title?
- [x] Have you checked whether your jira ticket required DOCSP changes?
- [x] Have you checked for release_note changes?

## Reminder (Please remove this when merging)
- Please try to Approve or Reject Changes the PR, keep PRs in review as
short as possible
- Our Short Guide for PRs:
[Link](https://docs.google.com/document/d/1T93KUtdvONq43vfTfUt8l92uo4e4SEEvFbIEKOxGr44/edit?tab=t.0)
- Remember the following Communication Standards - use comment prefixes
for clarity:
  * **blocking**: Must be addressed before approval.
  * **follow-up**: Can be addressed in a later PR or ticket.
  * **q**: Clarifying question.
  * **nit**: Non-blocking suggestions.
  * **note**: Side-note, non-actionable. Example: Praise 
  * --> no prefix is considered a question

---------

Co-authored-by: Mikalai Radchuk <[email protected]>

Author: MaciejKaras

requirements.txt

@@ -33,6 +33,7 @@ pytest-mock==3.14.1
 wrapt==1.17.2
 botocore==1.39.4
 boto3==1.39.4
+python-frontmatter==1.1.0
 
 # from kubeobject
 freezegun==1.5.3

scripts/release/__init__.py

@@ -0,0 +1 @@
+# Makes 'release' a Python package.

scripts/release/calculate_next_version.py

@@ -0,0 +1,60 @@
+import argparse
+import pathlib
+
+from git import Repo
+
+from scripts.release.changelog import (
+    DEFAULT_CHANGELOG_PATH,
+    DEFAULT_INITIAL_GIT_TAG_VERSION,
+)
+from scripts.release.release_notes import calculate_next_version_with_changelog
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Calculate the next version based on the changes since the previous version tag.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        "-p",
+        "--path",
+        default=".",
+        metavar="",
+        action="store",
+        type=pathlib.Path,
+        help="Path to the Git repository. Default is the current directory '.'",
+    )
+    parser.add_argument(
+        "-c",
+        "--changelog-path",
+        default=DEFAULT_CHANGELOG_PATH,
+        metavar="",
+        action="store",
+        type=str,
+        help=f"Path to the changelog directory relative to the repository root. Default is '{DEFAULT_CHANGELOG_PATH}'",
+    )
+    parser.add_argument(
+        "-s",
+        "--initial-commit-sha",
+        metavar="",
+        action="store",
+        type=str,
+        help="SHA of the initial commit to start from if no previous version tag is found.",
+    )
+    parser.add_argument(
+        "-v",
+        "--initial-version",
+        default=DEFAULT_INITIAL_GIT_TAG_VERSION,
+        metavar="",
+        action="store",
+        type=str,
+        help=f"Version to use if no previous version tag is found. Default is '{DEFAULT_INITIAL_GIT_TAG_VERSION}'",
+    )
+    args = parser.parse_args()
+
+    repo = Repo(args.path)
+
+    version, _ = calculate_next_version_with_changelog(
+        repo, args.changelog_path, args.initial_commit_sha, args.initial_version
+    )
+
+    print(version)

scripts/release/changelog.py

@@ -0,0 +1,164 @@
+import datetime
+import os
+import re
+from enum import StrEnum
+
+import frontmatter
+from git import Commit, Repo
+
+DEFAULT_CHANGELOG_PATH = "changelog/"
+DEFAULT_INITIAL_GIT_TAG_VERSION = "1.0.0"
+FILENAME_DATE_FORMAT = "%Y%m%d"
+FRONTMATTER_DATE_FORMAT = "%Y-%m-%d"
+MAX_TITLE_LENGTH = 50
+
+
+class ChangeKind(StrEnum):
+    PRELUDE = "prelude"
+    BREAKING = "breaking"
+    FEATURE = "feature"
+    FIX = "fix"
+    OTHER = "other"
+
+    @staticmethod
+    def from_str(kind_str: str) -> "ChangeKind":
+        kind_str_lower = kind_str.lower()
+        if kind_str_lower == str(ChangeKind.PRELUDE):
+            return ChangeKind.PRELUDE
+        if kind_str_lower == str(ChangeKind.BREAKING):
+            return ChangeKind.BREAKING
+        elif kind_str_lower == str(ChangeKind.FEATURE):
+            return ChangeKind.FEATURE
+        elif kind_str_lower == str(ChangeKind.FIX):
+            return ChangeKind.FIX
+        elif kind_str_lower == str(ChangeKind.OTHER):
+            return ChangeKind.OTHER
+        raise ValueError(f"unknown change kind: {kind_str}")
+
+
+class ChangeEntry:
+    def __init__(self, date: datetime, kind: ChangeKind, title: str, contents: str):
+        self.date = date
+        self.kind = kind
+        self.title = title
+        self.contents = contents
+
+
+def get_changelog_entries(
+    base_commit: Commit,
+    repo: Repo,
+    changelog_sub_path: str,
+) -> list[ChangeEntry]:
+    changelog = []
+
+    # Compare base commit with current working tree
+    diff_index = base_commit.diff(other=repo.head.commit, paths=changelog_sub_path)
+
+    # No changes since the previous version
+    if not diff_index:
+        return changelog
+
+    # Traverse added Diff objects only (change type 'A' for added files)
+    # Because we are traversing back to the most recent version, we only care about files that were added since then
+    # If a file was added in one commit and then modified in another, we only care about the final version of the file
+    # Same for deletions - if file was added in one commit but then deleted in another, we don't want to include it
+    # in the Release Notes
+    for diff_item in diff_index.iter_change_type("A"):
+        file_path = diff_item.b_path
+
+        change_entry = extract_changelog_entry(repo.working_dir, file_path)
+        changelog.append(change_entry)
+
+    return changelog
+
+
+def extract_changelog_entry(working_dir: str, file_path: str) -> ChangeEntry:
+    file_name = os.path.basename(file_path)
+    date, kind = extract_date_and_kind_from_file_name(file_name)
+
+    abs_file_path = os.path.join(working_dir, file_path)
+    with open(abs_file_path, "r") as file:
+        file_content = file.read()
+
+    change_entry = extract_changelog_entry_from_contents(file_content)
+
+    if change_entry.date != date:
+        raise Exception(
+            f"{file_name} - date in front matter '{change_entry.date}' does not match date extracted from file name '{date}'"
+        )
+
+    if change_entry.kind != kind:
+        raise Exception(
+            f"{file_name} - kind in front matter '{change_entry.kind}' does not match kind extracted from file name '{kind}'"
+        )
+
+    return change_entry
+
+
+def extract_date_and_kind_from_file_name(file_name: str) -> (datetime, ChangeKind):
+    match = re.match(r"(\d{8})_([a-zA-Z]+)_(.+)\.md", file_name)
+    if not match:
+        raise Exception(f"{file_name} - doesn't match expected pattern")
+
+    date_str, kind_str, _ = match.groups()
+    try:
+        date = parse_change_date(date_str, FILENAME_DATE_FORMAT)
+    except Exception as e:
+        raise Exception(f"{file_name} - {e}")
+
+    try:
+        kind = ChangeKind.from_str(kind_str)
+    except Exception as e:
+        raise Exception(f"{file_name} - {e}")
+
+    return date, kind
+
+
+def parse_change_date(date_str: str, date_format: str) -> datetime:
+    try:
+        date = datetime.datetime.strptime(date_str, date_format).date()
+    except Exception:
+        raise Exception(f"date '{date_str}' is not in the expected format {date_format}")
+
+    return date
+
+
+def extract_changelog_entry_from_contents(file_contents: str) -> ChangeEntry:
+    data = frontmatter.loads(file_contents)
+
+    kind = ChangeKind.from_str(str(data["kind"]))
+    date = parse_change_date(str(data["date"]), FRONTMATTER_DATE_FORMAT)
+    ## Add newline to contents so the Markdown file also contains a newline at the end
+    contents = data.content + "\n"
+
+    return ChangeEntry(date=date, title=str(data["title"]), kind=kind, contents=contents)
+
+
+def get_changelog_filename(title: str, kind: ChangeKind, date: datetime) -> str:
+    sanitized_title = sanitize_title(title)
+    filename_date = datetime.datetime.strftime(date, FILENAME_DATE_FORMAT)
+
+    return f"{filename_date}_{kind}_{sanitized_title}.md"
+
+
+def sanitize_title(title: str) -> str:
+    # Only keep alphanumeric characters, dashes, underscores and spaces
+    regex = re.compile("[^a-zA-Z0-9-_ ]+")
+    title = regex.sub("", title)
+
+    # Replace multiple dashes, underscores and spaces with underscores
+    regex_underscore = re.compile("[-_ ]+")
+    title = regex_underscore.sub(" ", title).strip()
+
+    # Lowercase and split by space
+    words = [word.lower() for word in title.split(" ")]
+
+    result = words[0]
+
+    for word in words[1:]:
+        if len(result) + len("_") + len(word) <= MAX_TITLE_LENGTH:
+            result = result + "_" + word
+        else:
+            break
+
+    return result

scripts/release/changelog_test.py

@@ -0,0 +1,110 @@
+import datetime
+import unittest
+
+from scripts.release.changelog import (
+    MAX_TITLE_LENGTH,
+    ChangeKind,
+    extract_changelog_entry_from_contents,
+    extract_date_and_kind_from_file_name,
+    sanitize_title,
+)
+
+
+class TestExtractChangelogDataFromFileName(unittest.TestCase):
+    def test_prelude(self):
+        date, kind = extract_date_and_kind_from_file_name("20250502_prelude_release_notes.md")
+        self.assertEqual(date, datetime.date(2025, 5, 2))
+        self.assertEqual(kind, ChangeKind.PRELUDE)
+
+    def test_breaking_changes(self):
+        date, kind = extract_date_and_kind_from_file_name("20250101_breaking_api_update.md")
+        self.assertEqual(date, datetime.date(2025, 1, 1))
+        self.assertEqual(kind, ChangeKind.BREAKING)
+
+    def test_features(self):
+        date, kind = extract_date_and_kind_from_file_name("20250509_feature_new_dashboard.md")
+        self.assertEqual(date, datetime.date(2025, 5, 9))
+        self.assertEqual(kind, ChangeKind.FEATURE)
+
+    def test_fixes(self):
+        date, kind = extract_date_and_kind_from_file_name("20251210_fix_olm_missing_images.md")
+        self.assertEqual(date, datetime.date(2025, 12, 10))
+        self.assertEqual(kind, ChangeKind.FIX)
+
+    def test_other(self):
+        date, kind = extract_date_and_kind_from_file_name("20250520_other_update_readme.md")
+        self.assertEqual(date, datetime.date(2025, 5, 20))
+        self.assertEqual(kind, ChangeKind.OTHER)
+
+    def test_invalid_date(self):
+        with self.assertRaises(Exception) as context:
+            extract_date_and_kind_from_file_name("20250640_other_codebase.md")
+        self.assertEqual(
+            str(context.exception),
+            "20250640_other_codebase.md - date '20250640' is not in the expected format %Y%m%d",
+        )
+
+    def test_wrong_file_name_format_date(self):
+        with self.assertRaises(Exception) as context:
+            extract_date_and_kind_from_file_name("202yas_other_codebase.md")
+        self.assertEqual(str(context.exception), "202yas_other_codebase.md - doesn't match expected pattern")
+
+    def test_wrong_file_name_format_missing_title(self):
+        with self.assertRaises(Exception) as context:
+            extract_date_and_kind_from_file_name("20250620_change.md")
+        self.assertEqual(str(context.exception), "20250620_change.md - doesn't match expected pattern")
+
+
+def test_strip_changelog_entry_frontmatter():
+    file_contents = """
+---
+title: This is my change
+kind: feature
+date: 2025-07-10
+---
+
+* **MongoDB**: public search preview release of MongoDB Search (Community Edition) is now available.
+  * Added new property [spec.search](https://www.mongodb.com/docs/kubernetes/current/mongodb/specification/#spec-search) to enable MongoDB Search.
+"""
+
+    change_entry = extract_changelog_entry_from_contents(file_contents)
+
+    assert change_entry.title == "This is my change"
+    assert change_entry.kind == ChangeKind.FEATURE
+    assert change_entry.date == datetime.date(2025, 7, 10)
+    assert (
+        change_entry.contents
+        == """* **MongoDB**: public search preview release of MongoDB Search (Community Edition) is now available.
+  * Added new property [spec.search](https://www.mongodb.com/docs/kubernetes/current/mongodb/specification/#spec-search) to enable MongoDB Search.
+"""
+    )
+
+
+class TestSanitizeTitle(unittest.TestCase):
+    def test_basic_case(self):
+        self.assertEqual(sanitize_title("Simple Title"), "simple_title")
+
+    def test_non_alphabetic_chars(self):
+        self.assertEqual(sanitize_title("Title tha@t-_ contain's strange char&s!"), "title_that_contains_strange_chars")
+
+    def test_with_numbers_and_dashes(self):
+        self.assertEqual(sanitize_title("Title with 123 numbers to-go!"), "title_with_123_numbers_to_go")
+
+    def test_mixed_case(self):
+        self.assertEqual(sanitize_title("MiXeD CaSe TiTlE"), "mixed_case_title")
+
+    def test_length_limit(self):
+        long_title = "This is a very long title that should be truncated because it exceeds the maximum length"
+        sanitized_title = sanitize_title(long_title)
+        self.assertTrue(len(sanitized_title) <= MAX_TITLE_LENGTH)
+        self.assertEqual(sanitized_title, "this_is_a_very_long_title_that_should_be_truncated")
+
+    def test_leading_trailing_spaces(self):
+        sanitized_title = sanitize_title("  Title with spaces  ")
+        self.assertEqual(sanitized_title, "title_with_spaces")
+
+    def test_empty_title(self):
+        self.assertEqual(sanitize_title(""), "")
+
+    def test_only_non_alphabetic(self):
+        self.assertEqual(sanitize_title("!@#"), "")