Changelog / Version Differences

grant commented 3 years ago

Hello CE folks,

Does the CE spec have a changelog? I wish to know the differences between 1.0.0 and 1.0.1 for our libraries. I assume there are no breaking changes, but I cannot find a changelog summarizing the changes.

A CHANGELOG.md or summarized version cut in https://github.com/cloudevents/spec/releases/tag/v1.0.1 would be nice.

Example

https://github.com/facebook/react/blob/master/CHANGELOG.md

(There are tools to help like https://github.com/apps/semantic-pull-requests)

It seems like we could categorize PRs with conventional commit (like docs:, fix:) and then group changes appropriately.

Current note:

Add protobuf format as a sub-protocol - #721
Allow JSON values to be null, meaning unset - #713
[Primer] Adding a Non-Goal w.r.t Security - #712
WebSockets protocol binding - #697
Clarify difference between message mode and HTTP content mode - #672
add missing sdks to readme - #666
New sdk maintainers rules - #665
move sdk governance and cleanup - #663
Bring 'datadef' definition into line with specification - #658
Add CoC and move some governance docs into 'community' - #656
Add blog post around understanding Cloud Events interactions - #651
SDK governance draft - #649
docs: add common processes for SDK maintainers and contributors - #648
Adding Demo for Cloud Events Orchestration - #646
Clarified MUST requirement for JSON format - #644
Re-Introducing Protocol Buffer Representation - #626
Closes #615 - #616
Reworked Distributed Tracing Extension - #607
Minor updates to Cloud Events Primer - #600
Kafka clarifications - #599
Proprietary binding spec inclusion guide - #595
Adding link to Pub/Sub binding - #588
Add some clarity around SDK milestones - #584
How to determine binary CE vs random non-CE message - #577
Adding Visual Studio Code extension to community open-source doc - #573
Specify encoding of kafka header keys and values and message key - #572
Fix distributed tracing example - #569
Paragraph about nested events to the primer - #567
add rules for changing Admins- #564
Updating JSON Schema - #563
Say it's ok to ignore non-MUST recommendations - at your own risk - #562
Update Distributed Tracing extension spec links - #550
Add Ruby SDK to SDK lists - #548

An SDK wants support 1.0.1, and I'd like to see changes between 1.0.1 and 1.0.0.

duglin commented 3 years ago

I'm confused - isn't the list you pasted above the changelog you're looking for?

grant commented 3 years ago

The list of commits and their number is a minimal change, but I'd expect:

A CHANGELOG.md file
More useful information about what actually changed. It's hard for me to understand what actual changes to the spec made it through to 1.0.1
- For example, I'd expect Added/Changed/Removed sections like this: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
- Or a higher level summary of what changed. Like why was release 1.0.1 cut and what should I care about?

I wasn't able to find the changes easily. Hope my perspective makes sense.

grant commented 3 years ago

Per chat, some groupings of changes would be useful.

May be a duplicate of https://github.com/cloudevents/spec/issues/687 (diffing 0.3 and 1.0 spec)

AI: Create a PR to add that CHANGELOG file. (We all agree that would be useful)

Also look at the the JS SDK release note process.

duglin commented 3 years ago

closed via #784

cloudevents / spec

Changelog / Version Differences #755

Example

Current note: