Add changelog management tooling and backfill existing release history #45

jonathan343 · 2026-01-04T01:34:57Z

Note

These scripts are adapted from smithy-lang/smithy-python#552, with the addition of support for release summary entries (SUMMARY.json).

Summary

Add Python scripts for managing per-package changelogs in a structured, automation-friendly format.
Backfill changelog entries for existing client packages (aws-sdk-bedrock-runtime, aws-sdk-sagemaker-runtime-http2, aws-sdk-transcribe-streaming).

Changelog Tooling

This PR introduces three scripts under scripts/changelog/:

Script	Purpose
`new-entry.py`	Create individual changelog entries stored in `.changes/next-release/`
`new-release.py`	Consolidate pending entries into a versioned JSON file (e.g., `0.3.0.json`)
`render.py`	Generate `CHANGELOG.md` from version JSON files using a Jinja2 template

Workflow

Contributors add entries via new-entry.py --package <name> --type <type> --description "..."
At release time, new-release.py consolidates entries into <version>.json
render.py regenerates CHANGELOG.md from all version files

Test plan

Verify new-entry.py creates entries in the correct location
Verify new-release.py consolidates entries and cleans up next-release/
Verify render.py generates accurate CHANGELOG.md output
Confirm rendered changelogs match the JSON source data

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

- new-entry.py allows for creating entried for a specific package, type, and a description. - new-release.py consolidates new entries into a versioned json file for preservation. - render.py will generate a CHANGELOG.md file using the versioned json files and a jinja2 template.

…bedrock-runtime

…transcribe-streaming

…sagemaker-runtime-http2

ubaskota

Overall looks good. I've added some comments. Please, let me know if you have any questions.

clients/aws-sdk-bedrock-runtime/.changes/0.0.1.json

ubaskota · 2026-01-06T16:18:08Z

scripts/changelog/new-entry.py

+    # Get package .changes directory and ensure it exists
+    changes_dir = get_package_changes_dir(package_name)
+    changes_dir.mkdir(exist_ok=True)
+
+    # Create next-release directory for pending changes
+    next_release_dir = changes_dir / "next-release"
+    next_release_dir.mkdir(exist_ok=True)


Both create_change_entry and create_summary_entry functions repeat the same logic for directory setup. Do you think they can be consolidated into a single function?

+1; I'm not sure I understand the reason for duplicating this logic. It's minor, but this could easily be one function:

def ensure_changes_dir(package_name): changes_dir = PROJECT_ROOT_DIR / "clients" / package_name / ".changes" changes_dir.mkdir(parents=True, exist_ok=True) return changes_dir

ubaskota · 2026-01-06T16:36:29Z

scripts/changelog/new-entry.py

+) -> str:
+    """Create or update the release summary for the next release."""
+    # Get package .changes directory and ensure it exists
+    changes_dir = get_package_changes_dir(package_name)


Will there be a case where the package_name is invalid? Do we need to add a validation?

If it doesn't exist, we'll get the following error:

FileNotFoundError: [Errno 2] No such file or directory: '/Users/gytndd/dev/GitHub/aws-sdk-python/clients/aws-sdk-bedrock-runtimes/.changes'

I can add a better error message

ubaskota · 2026-01-06T17:27:45Z

scripts/changelog/render.py

+            versions.append(file.stem)
+
+    # Sort by semantic version (oldest first)
+    versions.sort(key=lambda v: [int(x) for x in v.split(".")])


Nit: Would using versions.sort(key=.., reverse=True) be better than reversing the sorted list inside render_changes?

Either one works tbh. I'll add a reverse parameter to get_sorted_versions and provide True when we call it

ubaskota · 2026-01-06T17:32:00Z

scripts/changelog/new-entry.py

+    # Generate unique filename
+    timestamp = int(time.time() * 1_000_000)
+    unique_id = uuid.uuid4().hex
+    filename = f"{package_name}-{change_type}-{timestamp}-{unique_id}.json"


For filename, timestamp is already in microseconds. Wouldn't that be enough? What is the benefit of adding uuid to it?

Relying on timestamps alone will never really guarantee uniqueness since our infra will be creating changelog entries in rapid succession (and in parallel in the future). See the example below:

>>> timestamps = [] >>> for i in range(1000): ... timestamp = int(time.time() * 1_000_000) ... if timestamp in timestamps: ... print("Found duplicate") ... else: ... timestamps.append(timestamp) ... Found duplicate Found duplicate Found duplicate

We could increase the precision, however, using uuid is more robust. I decided to include the timestamp in attempt to achieve natural ordering of changelog entries when rendering them out. However, that isn't really working right now and I'll handle it in a separate PR. It's more of a nice to have.

I'm gonna remove timestamp for now and only use uuid.

SamRemis · 2026-01-09T20:13:28Z

clients/aws-sdk-bedrock-runtime/.changes/0.3.0.json

+    },
+    {
+      "type": "dependency",
+      "description": "**Updated**: `smithy_aws_core[eventstream, json]` from `~=0.2.0` to `~=0.3.0`."


This seems like an odd thing to bold to begin with, and it is less readable (for me) in both JSON and markdown.

Not a huge thing, and we shouldn't change them retroactively, but if we are going to start using markdown syntax in changelog entries, we should agree on guidelines for when and how to apply them and record them in our contributing.md file.

SamRemis · 2026-01-09T20:22:13Z

scripts/changelog/new-entry.py

+def get_package_changes_dir(package_name: str) -> Path:
+    package_path = PROJECT_ROOT_DIR / "clients" / package_name
+    changes_dir = package_path / ".changes"
+    return changes_dir


Nit:
Personally I don't find this any more readable than a single line function of return PROJECT_ROOT_DIR / "clients" / package_name / ".changes".

If you do or prefer this for any reason, keep it as is.

SamRemis · 2026-01-09T20:25:28Z

scripts/changelog/new-entry.py

+    # Get package .changes directory and ensure it exists
+    changes_dir = get_package_changes_dir(package_name)
+    changes_dir.mkdir(exist_ok=True)
+
+    # Create next-release directory for pending changes
+    next_release_dir = changes_dir / "next-release"
+    next_release_dir.mkdir(exist_ok=True)


+1; I'm not sure I understand the reason for duplicating this logic. It's minor, but this could easily be one function:

def ensure_changes_dir(package_name): changes_dir = PROJECT_ROOT_DIR / "clients" / package_name / ".changes" changes_dir.mkdir(parents=True, exist_ok=True) return changes_dir

SamRemis · 2026-01-09T20:51:16Z

scripts/changelog/new-entry.py

+    parser.add_argument(
+        "-t",
+        "--type",
+        # TODO: Remove the 'breaking' option once this project is stable.


Just a thought- maybe we leave this in permanently? For minor "breaks" that we will continue to do that offer more benefit than pain to customers.

One example that may be upcoming in boto is switching to using standard instead of legacy retry mode.

SamRemis · 2026-01-09T21:19:58Z

scripts/changelog/new-release.py

+        version_data["summary"] = summary
+
+    with open(version_file, "w") as f:
+        json.dump(version_data, f, indent=2)


Suggested change

json.dump(version_data, f, indent=2)

json.dump(version_data, f, indent=2)

f.write("\n")

Adding a newline at the end of the file will prevent git from showing the warning and help with tools that prefer files end in newlines.

SamRemis · 2026-01-09T21:24:10Z

scripts/changelog/new-release.py

+                entry_file.unlink()
+                removed_count += 1
+            except OSError as e:
+                print(f"Warning: Could not remove {entry_file}: {e}", file=sys.stderr)


The intention here is to ignore the error quietly and continue? Do you think it's possible that this error will get ignored and leave behind the entry file and duplicate the entry for the next release?

jonathan343 added 4 commits January 3, 2026 19:24

Add changelog entries, releases, and render CHANGELOG.md for aws-sdk-…

d8473d8

…bedrock-runtime

Add changelog entries, releases, and render CHANGELOG.md for aws-sdk-…

026d02c

…transcribe-streaming

Add changelog entries, releases, and render CHANGELOG.md for aws-sdk-…

9d10c2f

…sagemaker-runtime-http2

jonathan343 marked this pull request as ready for review January 4, 2026 02:58

jonathan343 requested a review from a team as a code owner January 4, 2026 02:58

jonathan343 requested review from SamRemis and ubaskota January 5, 2026 21:53

ubaskota reviewed Jan 6, 2026

View reviewed changes

SamRemis reviewed Jan 9, 2026

View reviewed changes

	json.dump(version_data, f, indent=2)
	json.dump(version_data, f, indent=2)
	f.write("\n")

Add changelog management tooling and backfill existing release history #45

Are you sure you want to change the base?

Add changelog management tooling and backfill existing release history #45

Uh oh!

Conversation

jonathan343 commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changelog Tooling

Workflow

Test plan

Uh oh!

ubaskota left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jonathan343 commented Jan 4, 2026 •

edited

Loading