Add changelog management tooling and backfill existing release history #45
Conversation
ubaskota
left a comment
ubaskota
left a comment
There was a problem hiding this comment.
Overall looks good. I've added some comments. Please, let me know if you have any questions.
scripts/changelog/new-entry.py
Outdated
| # 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" |
There was a problem hiding this comment.
For filename, timestamp is already in microseconds. Wouldn't that be enough? What is the benefit of adding uuid to it?
There was a problem hiding this comment.
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 duplicateWe 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.
| }, | ||
| { | ||
| "type": "dependency", | ||
| "description": "**Updated**: `smithy_aws_core[eventstream, json]` from `~=0.2.0` to `~=0.3.0`." |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yea, we can get something added in CONTRIBUTING.md. That should probably be done in a separate PR since there are non-changelog things we should also update it with.
I'm curious what about the bold syntax makes it less readable for you?
scripts/changelog/new-entry.py
Outdated
| parser.add_argument( | ||
| "-t", | ||
| "--type", | ||
| # TODO: Remove the 'breaking' option once this project is stable. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I'm not against it. I think there should be some confirmation that explains the effects of using breaking and that it should be used sparingly. Probably wouldn't hurt to add the same for a feature since they both result in minor bumps across the ecosystem.
I'll update to:
# TODO: Prompt the user for confirmation before allowing the 'breaking' or `feature` options.
scripts/changelog/new-release.py
Outdated
| entry_file.unlink() | ||
| removed_count += 1 | ||
| except OSError as e: | ||
| print(f"Warning: Could not remove {entry_file}: {e}", file=sys.stderr) |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I think this would be a very rare case when this happens (if possible) because of how we're using this. I'll remove the try/except so if this does raise an error, our script and release process fail
- 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.
…transcribe-streaming
…sagemaker-runtime-http2
jonathan343
force-pushed
the
changelog-management
branch
from
9d10c2f to
f7316a8
Compare
3 participants
Note
These scripts are adapted from smithy-lang/smithy-python#552, with the addition of support for release summary entries (
SUMMARY.json).Summary
aws-sdk-bedrock-runtime,aws-sdk-sagemaker-runtime-http2,aws-sdk-transcribe-streaming).Changelog Tooling
This PR introduces three scripts under
scripts/changelog/:new-entry.py.changes/next-release/new-release.py0.3.0.json)render.pyCHANGELOG.mdfrom version JSON files using a Jinja2 templateWorkflow
new-entry.py --package <name> --type <type> --description "..."new-release.pyconsolidates entries into<version>.jsonrender.pyregeneratesCHANGELOG.mdfrom all version filesTest plan
new-entry.pycreates entries in the correct locationnew-release.pyconsolidates entries and cleans upnext-release/render.pygenerates accurateCHANGELOG.mdoutputBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.