BREAKING CHANGES

[thinkingserious]

As a result of your feedback and as a continuation of the execution of our long term roadmap, there will be breaking changes coming soon. The last time we had a major breaking change, it was for the implementation of v3 Web API support. We announced those changes here on GitHub along with some instructions on how to test and provide feedback.

The feedback we got was amazing, but we didn't quite get the amount or thoroughness of feedback we were hoping for.

We want to continue improving this iterative process, so we are reaching out to you for feedback in order to determine the optimum way to move forward as this library is designed to be community driven, SendGrid led.

Please take a moment to share your thoughts with us.

Following are some ideas we are considering, we will likely choose one from Execution and one from Communication, but not all of the items below.

Execution (for large changes):

1. Utilize the pre-release functionality in GitHub to gather feedback and contributions to a specific branch
2. Communicate through a dedicated GitHub issue that references that pre-release branch (e.g C# Dynamic Update)

Communication:

1. Continue using GitHub issues
2. Opt-in email newsletter for announcements
3. Opt-in email mailing list
4. Dedicated social media account (e.g. @sendgrid_libraries)

How do you prefer to get these announcements? Is this too much? Too little? Please let us know!!

As always, we are listening carefully and are looking forward to working with you.

Note: We will always follow the semver.org convention of using major point releases to signify breaking changes. Please DO NOT auto-update your dependencies. It is important to take a look at the CHANGELOG or releases to find out how the breaking changes will impact your code.

[adammenges]

what are the changes benefits?

[thinkingserious]

Hi @adammenges,

Here is one example:

We would like to refactor the Mail Helper so that:

1. Error handling is awesome
2. Common use cases are covered (e.g. templates, attachments, various permutations of tos/ccs and bccs
3. Data validation on the request body before sending the API request
4. Code refactored to be more Pythonic (e.g. use properties)

It could be that we can make those changes without a major breaking version bump, but in the case that we need to, we are trying to learn how this community would like to best communicate with us. Also, even it's not a breaking change, we would love more community collaboration on major changes.

Please let me know if you would like further clarification and thanks for taking the time to reach out to us!

[BillBrower]

I like the idea of an opt-in mailing list for communication. It'd have a higher signal/noise ratio than "watching" the repo on Github. If I got an email asking for feedback about specific changes I'd reply for sure, whereas I'd probably ignore an email from github telling me that a new issue had been opened.

[dedayoa]

I'd say for execution, go with the dedicated Github issue. IMO, issues are more "front and centre"
Communication, I've found the github issues, repo watching and summaries by email, a good way to stay in the loop.
Only No I can give is about the dedicated social media account...that'd be too much to keep tabs on.

[b-jam]

When an update for a package available, I will always go straight to GitHub to read release notes anyway.
So instant notification is not necessary as users will read the changes when its relevant for them to update.
However, the issue I have with your guys breaking changes is that its very difficult to find out what it will break, and how to fix that. So even though I can see "BREAKING CHANGE" in the changelog, I'll have to go into the release diff to try work out what it will be myself.

[thinkingserious]

That's great feedback @pa-jama!

I've updated our release checklist to include a line that emphasizes that we need to include specifics when making a breaking changes, both in the CHANGELOG and in the Releases section.

Thanks again for taking the time to reach out to us and helping us improve the SendGrid experience :)