Cherry
commented
1 month ago After discussing this with an active maintainer on this project (@jacobbednarz), it seems there is no real intention to follow semver for 3.x for the foreseeable future. Any communication in the README that stated it would at the start of the project was an accidental miscommunication.
Breaking changes will be released without following semver and if it breaks your application, that's at your own peril for using this library and not pinning to a specific version. That's despite this package previously following semver at versions prior to 3.x, and setting that expectation both within the npm ecosystem, and by this own package's history.
It's an extremely unfortunate situation, and I'm disappointed that it's the direction Cloudflare has chosen with their new SDK packages. It's worsened by the fact that there's no usable release notes between versions either, so this all just results in a significantly degraded developer experience at this time, going against all of the goals and prospects of this library and the blog post announcing it.
Hopefully this issue can remain open and further updates provided as this v3.x becomes as usable as v2.x in terms of stability and reliability, and developers can start relying on v3.x in the near future for production applications and workflows.
jacobbednarz
There's the Workers Script Settings endpoint, available at
https://api.cloudflare.com/client/v4 /accounts/{account_id}/workers/scripts/{script_name}/settings, via https://developers.cloudflare.com/api/operations/worker-script-get-settingsv3.0.0ofcloudflarereturned this response withbindings,compatibility_date, etc. viacloudflare.workers.scripts.settings.get(...)and it worked fine.Since then,
cloudflare.workers.scripts.settings.get(...)has had its behaviour completely changed, and now responds with just the/script-settingsresponse, so only responds withlogpush, andtail_consumers.When asked about this, folks were told they "should" be using another endpoint instead: https://discord.com/channels/595317990191398933/1225594037919285408/1264344172471652492. And apparently this endpoint is being deprecated: https://discord.com/channels/595317990191398933/1225594037919285408/1264699048468680826
But this hasn't been mentioned anywhere else, nor any user education has happened around the change.
(to be clear, I'm not against the deprecation of these endpoints - I think moving to versioned ones is good, but it can't be done so haphazardly as it was done here in the typescript SDK)
The release notes for
cloudflare-typescriptincludes:To start, I don't believe this is good for a stable SDK published as v3.0.0. What is the definition of a "minor breaking change"? And why is this a full release version if that's the case, and not still in beta? A "minor" breaking change, in my opinion, is only ever acceptable in a minor version as of a result of a security issue.
But, let's assume for a second that this was considered a "minor breaking change", and it was okay to break it (it wasn't in my opinion), the method that used to call this (
cloudflare.workers.scripts.settings.get) had it's behaviour completely changed! It'd be one thing if the method was removed and folks code errored immediately, but for it to change subtly like this is really not good.But, let's assume that it was deemed (somehow) acceptable to do that, and just let people know. There is NO WAY to discern this from the release notes today. They're simply incomprehensible, and it's impossible to see what's changed (breaking change or not), so folks are once again left to relying on types to tell them when things are wrong (which are incorrect for many methods/responses), or wait until they hit some breakage in production because they weren't told what was changed or how to update their code.
Recently, the README was updated and some notes about taking backwards compatibility were removed: https://github.com/cloudflare/cloudflare-typescript/commit/8bf5e89599793d44d6b8941795703129a362b510. I really hope this is reconsidered, and you're still keen for feedback. A new warning to "use a previous major version", or to essentially just deal with breaking changes without any migration guides or changelogs is extremely frustrating.
I understand it may be noted that this is all limited by API schemas, but that's a really disappointing answer when folks might reasonably rely on a library like this. Some extra care and effort really needs to be taken here, because as it currently stands, it's really hard to recommend anyone use this library if they value stability.