CLOUDP-295785 - Calculate next version and release notes script

[MaciejKaras]

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.

➜  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

➜  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 the repository root. 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, major' for breaking change entries
                          - 'feat, feature' for feature entries
                          - 'fix, bugfix, hotfix, patch' for bugfix entries
                          - everything else will be treated as other entries

3. scripts.release.release_notes.py -> create release notes based on the changes since last release tag

➜  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

• Have you linked a jira ticket and/or is the ticket in the title?
• Have you checked whether your jira ticket required DOCSP changes?
• 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
• 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

[m1kola]

I haven't reviewed everything, but I've tried the workflow with creating release notes and rendering it. Works really well. The only thing I noticed is that "Other Changes" section doesn't render (see a comment below with the reason).

[Julien-Ben]

Awesome changes, and tests 👏

[m1kola]

I've got a few questions, nits and suggestions. But overall I think it looks great.

[m1kola]

Could you please add a more detailed comment here or a docstring to the function explaining how this works? E.g. why we only getting added files? How do we account for modified changelog entries (e.g. added in one commit, modified in another)? Deleted?

This will be extremity helpful for the future us who will be maintaining the tool/making changes here.

[m1kola]

I'm looking at the tests: e.g. 20250520_docs_update_readme and 20250610_refactor_codebase.

And I think we should make other to be explicit and reject anything else.

[MaciejKaras]

I deliberately wanted to have some freedom in naming other kind of changes. The name other does not tell much, so if somebody wants to use docs or config they can and it will just land under Other changes.

Do you feel there is something wrong with this idea?

[m1kola]

With having random strings treated as other it is hard to tell if it is a real kind or not. Unless you remember implementation, it is hard to say in which section it will be rendered. E.g. will 20250520_docs_update_readme be rendered in features or in other? Or perhaps it is a prelude?

I think kind in file names and kind in front matter must always be consistent and explicit. This means that:

1. Let's not allow random strings in file names and in kind in front matter.
2. If one kind has multiple aliases (e.g. major and breaking) - let's choose one thing (e.g. major) as a canonical name and use it as a kind in both filenames and front matter.

So consistency in the data layer (files in our case), but flexibility on the client (CLI tool).

[MaciejKaras]

I agree that the kind in filename and in the file contents itself has to be identical. We are right now only checking if they map to the same ChangeKind value. I can easily change this and compare actual string representations.

Unless you remember implementation, it is hard to say in which section it will be rendered. E.g. will 20250520_docs_update_readme be rendered in features or in other? Or perhaps it is a prelude?
I don't find this true. The information about the mapping is presented in the CLI help of the method that creates a changelog file. I agree if we have less values to choose from it will be easier to memorize them and also see where the change will land in Release Notes just by scanning the filenames.

So you're proposing naming the same as the sections in the Release Notes template:

• breaking
• feature
• fix
• other
  ?

[m1kola]

I don't find this true. The information about the mapping is presented in the CLI help of the method that creates a changelog file.

Ok, I can say "unless you remember the implementation or look it up in the --help command". And still you need to read a multiline help string and catch "everything else will be treated as other entries".

So you're proposing naming the same as the sections in the Release Notes template:

I don't think it necessary has to be exact match with section names, but I would really want to have 1:1 mapping between sections and kinds in files. And I want the number of kind options to be deliberately very limited. Like prelude, major, feature, fix, other and that's it.

If we can make it dead simple we won't even need CLI to create change notes or read about how it works – just copy-paste existing one and modify it. Only read help if it fails to render (e.g. in CI). With limited number of options we can make it like so.

[m1kola]

I see you updated args in the function and removed defaults, but defaults are still mentioned here.