Breaking Changes Announcements

[Inumedia]

Hi, this feels like it should more of a discussion than an actual issue since it's more of a meta thing than an issue with the library itself:

Intro

I've been a user of this library since mid 2017 back in the very early days. Since I refactored my code to primarily use this instead of System.Drawing the use of managed-only code only has been a very significant benefit and saved me a lot of hassle when deploying to Linux. Since then, I've never really had any problems with ImageSharp and only have good things to say about its usability and performance.

Problem I'm running into

That being said, it seems like once a year there will be some major shake-up and pinned version of NuGet packages will get whole-sale deleted and some new system will get setup. While I understand this library is still considered non-stable from the development team here, and I don't want to step on toes for how you guys handle your deployment system, this causes a very significant and non-trivial amount of pain on my side.

My preferred use-case

I use this library primarily by picking a version and generally sticking with it (with the exception of bugs needing to get resolved, eg. #802 ) and will rarely update it unless I need to. This is largely due to defaults and APIs changing over time, and me not having time to update to the new standard (For example: the .Mutate change) or test for new bugs. This generally works and I rarely see any version-specific issues arise, and generally works so I can focus on maintaining my own code and adding features, etc. Until the pinned packages get deleted.

How this problem affects me

Every time the packages get deleted, I'm forced to upgrade to the newer versions of ImageSharp. This isn't always immediately known as I sometimes take months long breaks and won't see missing packages until potentially months after-the-fact. While I understand the need to upgrade and make large-scale API changes, and this is not in any way to vent about those changes, this forces me to drop everything I'm doing to instead focus on upgrading to the newer APIs instead of focusing on my own product.

As a note, while some could say "Well, just upgrade more regularly", trying to keep up-to-date is just not realistic. I have to maintain reading and writing raw pixel formats, handling pixel formats that aren't supported by default, creating gifs on the fly, creating images based on many other images, mutating images, scaling images, saving images, and creating large (4k+) images. While the API changes aren't always complex, defaults can change over time or I can end up stumbling on bugs ( eg. #1105 and #1100 ) and aren't discovered until after deployed and users have run into them in the wild.

Again, this isn't me trying to vent about random bugs or about API changes, this is about being forced into these bugs without notice. If this comes off as such, please let me know as that is not the intention.

Proposal

I'd like to suggest maybe starting something like https://github.com/aspnet/Announcements/ where announcements like this can be sent out before they happen, or maybe an index of breaking changes (and ideally how to fix) between versions, or an announcement of things breaking as/after they happen?

[tocsoft]

If you update to any version from nuget.org rather than one from our testing/unstable myget feed then you wont be hit by the issue of packages vanishing on you.

Basically if you are using our unstable feed that you have to update regularly or expect the package to go away, if you use nuget.org than expect those package to never go away (mostly because its not actually possible to remove versions from nuget.org).

Regarding breaking changes, every release we have pushed out to nuget that had major api changes has been announced/documented on our blog along with being announced on twitter.

[Inumedia]

If you update to any version from nuget.org rather than one from our testing/unstable myget feed then you wont be hit by the issue of packages vanishing on you.

Yeah, the pushing to NuGet is a pretty newer thing to me in regards to ImageSharp. It looks like there's some big lag between releases getting pushed to NuGet (the last month notwithstanding), but it sounds like you guys will be pushing there more regularly soon / stable?

For context on the MyGet getting deleted, I'm just a solo dev on a very large (unfunded / free to use) SaaS project that got full time employment after writing tons of code. My deployments are Docker images to a Kubernetes cluster. If I have to switch to a nightly again for a bugfix of ImageSharp and the MyGet suddenly gets deleted, I won't know until the next time I rebuild my docker images. If I need to fix a DoS attack vector in my code at the same time, I'm basically forced to (at best) make my users suffer for a while (or at worst be out significant hosting/bandwidth money) because I didn't know a more stable build got released and didn't upgrade ahead of time. I know this isn't your problem, but I'd greatly appreciate your consideration here. This is intended more as a sincere implore than a vent, I'm sorry if it comes off as the latter. To my original post, I'd at-least like a heads-up or something if possible so I can be prepared :)

Regarding breaking changes, every release we have pushed out to nuget that had major api changes has been announced/documented on our blog along with being announced on twitter.

Ah, I wasn't aware documented upgrade steps were posted on the blog and Twitter. I'll have to mark the Twitter for notifications. As for the blog, it doesn't look like there's a way to receive notifications from that which is really what I'm after. While Twitter can give me notifications, it's also very likely to get drowned out in other social activity. I'd greatly prefer something that sends an email in this context.

I see the Twitter has recent posts regarding the RC3, but it looks like the blog hasn't been updated since beta7? I'm also not seeing anything for SixLabors.ImageSharp.Drawing or SixLabors.Fonts specifically, or the breaking changes in those libraries?

How often and quickly can I expect to see breaking changes listed there? I know SixLabors is a pretty small team, and I feel like something more informal would be better suited for this as it would be easier to give advance notice / less full-blog-post-y.

[antonfirsov]

I think we will have a solution for this after 1.0 (which comes very soon):

1. If you need a comprehensive list of changes for new releases, I suggest to monitor our release notes. Unlike blog or twitter, it's automated now, so it doesn't depend on our capacity to fill it with content. Currently it's not possible to sort out the breaking PR-s in those lists however. This could be easily fixed by introducing a Breaking change label, so we can highlight those in future release notes. (@JimBobSquarePants thoughts?)
2. Since RC1, we push to NuGet more frequently, so you are less exposed to the unstable MyGet feed now. You should probably avoid it in production from now on. Whenever you need to update, you'll be able to review release notes, which should make the process more predictible on your side.
3. With 1.0 we will be API-stable (until the next major version bump). Like it happened in Default Gif RepeatCount to 1 #1100, behavioral breaking changes can still happen if it's necessary for a bugfix though, but those should be visible from release notes if we introduce a new label.

Do you think this will help with your concerns? I'm afraid, introducing anything more sophisticated and/or more ceremonial is simply outside of the capacity of our team.

[Inumedia]

This could be easily fixed by introducing a Breaking change label

I think this is a wonderful idea and if properly and regularly used would practically take care of the entire issue of breaking changes over time. This would make it considerably easier to investigate what changed when / how and how to upgrade in the context of a breaking change not being documented in release notes somewhere.

Since RC1, we push to NuGet more frequently

If this holds up, yeah my entire issue with packages disappearing / MyGet is a moot point. I'm sure there's going to be some case at some point that I ship with MyGet but it sounds like I should be able to easily switch back to stable.

With 1.0 we will be API-stable

Awesome, that sounds great. I'm sure at some point something will change, that's just life, but having that Breaking change label for those kinds of default behavioral changes would definitely be a blessing when trying to determine and resolve issues from users

---

I'm going to hold off marking this as answer until @JimBobSquarePants gives his feedback on that label, again I think it's a wonderful idea, but it really depends on what you guys decide to do as a team

[JimBobSquarePants]

@antonfirsov I think breaking should be enough of an identifier. Our notes are semi-automated. I hacked something together based on some old code I found that uses the OcktoKit library to configure notes but still have to do the process manually. I'm yet to find a Github action that does anything useful in that regard.

[antonfirsov]

@JimBobSquarePants yeah an action would be great. Meanwhile, if you can share the source of that script, I'm happy to hack it further.

[JimBobSquarePants]

I put together a website anyone can use to generate release notes. Seems to work pretty well and incorporates a "breaking" label filter.

https://github.com/JimBobSquarePants/GithubReleaseNotesGenerator
https://githubreleasenotes.azurewebsites.net/