HN Reader

But more to the point, go out of your way to avoid breaking backwards compatibility. If it's possible to achieve the same functionality a different way, just modify the deprecated function to use the new function in the background.

My biggest problem with the whole static typing trend is that it makes developers feel empowered to break backwards compatibility when it would be trivial to keep things working.

edit: Not that it is always trivial to avoid breaking backwards compatibility, but there are so many times that it would be.

How do you know? This is a wild assertion. This idea is terrible. I thought it was common knowledge that difficult to reproduce, seemingly random bugs are much more difficult to find and fix than compiler errors.

If you're ready to break your api, break your api. Don't play games with me. If more people actually removed deprecated APIs in a timely manner, then people will start taking it more seriously.

Better to give an actual timeline (future version & date) for when deprecated functionality / functions will be removed, and in the meantime, if the language supports it, mark those functions as deprecated (e.g. C++ [[deprecated]] attribute) so that developers see compilation warnings if they failed to read the release notes.

If it's no longer being maintained then put a depreciation warning and let it break on its own. Changing a deprecated feature just means you could maintain it but don't want to.

Alternatively if you want to aggressively push people to migrate to the new version, have a clear development roadmap and force a hard error at the end of the depreciation window so you know in advance how long you can expect it to work and can document your code accordingly.

This wishy-washy half-broken behaviour doesn't help anyone

We’ve sent out industry alerts, updated documentation and emailed all user. The problem is the contact information goes stale. The developer who initially registered and set up the keys, has moved on. The service has been running in production for years without problems and we’ve maintained backwards compatibility.

So do we just turn it off? We’ve put messages in the responses. But if it’s got 200ok we know no one is looking at those. We’ve discussed doing brownouts where we fail everything for an hour with clear error messages as to what is happening.

Is there a better approach? I can’t imagine returning wrong data on purpose randomly. That seems insane.

    WORKAROUND_URLLIB3_HEADER_DEPRECATION_THIS_IS_A_TEMPORARY_FIX_CHANGE_YOUR_CODE=1 python3 ...

Of course you can layer it with warnings as a first stage, but ultimately it's either this or remove the code outright (or never remove it and put up with whatever burden that imposes).

Instead, if you must, add a sleep within the function for 1 ms in the first release, 2 ms in the second release, and so on. But maybe just fix the tooling instead to make deprecations actually visible.

But intentionally breaking my users runtime in a way that's really hard and annoying to find? Is the author OK? This reads like a madman to me.

There are sophisticated users who care about the quality of their code and care about it breaking as infrequently as possible. Those users follow warnings. Not only warnings that happen by default; they use additional tooling to get extra warnings. The follow up on warnings.

Deprecation warnings serve those people.

As for the others, who cares. "We generously told you this would be removed, for years".

People who ignore warnings related to compatibility and have a workflow whereby your dependencies are not pinned down to specific versions, in some project configuration file, so that they are always getting the latest dependencies, are choosing to inflict breakages on themselves.

What if we found that a highway overpass construction material was suboptimal, and we want people to use superior materials, so, every now and then, we send a chunk of concrete plummeting down to the ground, to kill a motorist?

Thanks to deprecating like we mean it, they're going to replace that overpass sooner than they would otherwise. You'll thank me later.

From the https://sethmlarson.dev/deprecations-via-warnings-dont-work-... that the post opens with:

> This API was emitting warnings for over 3 years in a top-3 Python package by downloads urging libraries and users to stop using the API and that was not enough. We still received feedback from users that this removal was unexpected and was breaking dependent libraries.

Entirely predictable.

Even many of those who saw the deprecation logging, and bothered to make a conscious decision, didn't think you'd actually break the API.

> We ended up adding the APIs back and creating a hurried release to fix the issue.

Entirely predictable.

Save yourself some anguish, and don't break API unnecessarily. Treat it like a guarantee, as much as possible.

If it's a real problem for ongoing development, consider using SemVer and multiple versions, like the linked article suggests. (With the deprecated branch getting minimal maintenance: maybe only select bug fixes, or only critical security fixes, maybe with a sunset on even those, and a deprecation warning for the entire library when it's no longer supported.)

1. Start charging money for/of deprecated APIs. Just like Oracle did it with Java 8.

- OR -

2. Add a timestamp-based RuntimeException to the very same code-path. If the date is greater than (>) the deprecation date, simply throw RuntimeException. for 100% of the requests, all the time.

Yes, it will page someone, and yes, it will get fixed immediately!

IMO, any deprecation should go in the following steps:

1. Decide that you want to deprecate the thing. This also includes steps on how to migrate away from the thing, what to use instead, and how to keep the existing behaviour if needed. This step would also decide on the overall timeline, starting with the decision and ending with the removal.

2. Make the code give out big warnings for the deprecation. If there's a standard build system, it should have support for deprecation warnings.

3. Break the build in an easy to fix way. If there is too much red tape to take one of the recommended steps, the old API is still there, just under a `deprecated` flag or path. Importantly, this means that at this step, 'fixing' the build doesn't require any change in dependencies or (big) change in code. This should be a one line change to make it work.

4. Remove the deprecated thing. This step is NOT optional! Actually remove it. Keep it part of your compiler / library / etc in a way to give an error but still delete it. Fixing the build now requires some custom code or extra dependency. It is no longer a trivial fix (as trivial as the previous step at least).

Honestly, the build system should provide the tools for this. Being able to say that some item is deprecated and should warn or it is deprecated and should only be accessible if a flag is set or it is removed and the error message should say "function foo() was removed in v1.4.5. Refer to the following link:..." instead of just "function foo() not found"

If the build system has the option to treat warnings as errors, it should also have the option to ignore specific warnings from being treated as such (so that package updates can still happen while CI keeps getting the warning). The warning itself shouldn't be ignored.

The ideal flow, IMHO:

1: Emit warning, and include if possible a deadline ("will be removed in the next major version")

2: After X time, BEFORE the deadline, turn it into a compiler OR linter error, but keep the code

3: Do the appropriated notification in the channels about it of impending doom

4: Doom

If this is done correctly, we change the expectations from "warnings LOL!" to "warnings are serious business" that is missing in a lot of contexts

One day I came back from holidays. I had just broken a big go-live where the release number passed x. Date missed, next possibility in a few weeks. The team was pissed.

Yes they COULD have fixed the warnings. But breaking the go live was quite of of proportion for not doing so.

V 1.0 - foo introduced

V 1.1 - foo deprecated, recommend bar

V 2.0 - foo removed, only bar

Users can stay on 1.x indefinitely, even if it never receives updates. Development continues on 2.x, eventually 3.x and so on. Users only experience breaking changes when they manually do a major version upgrade.

Building it produces about two-three dozen deprecation warnings.

The whole software stack relies on a cluster of packages that stopped receiving updates 5 years ago.

The software is not facing end-users. But it does build using NPM and not via vendored packages.

To avoid those warnings, large parts of the code need to be rewritten using a different set of packages.

That doesn't get prioritised because it works.

The software sucks in many ways, but only from the perspective of an artisan.

The customer is happy to ignore warnings as long as the software does its job.

There isn't money in fixing things that work because it got old.

The incentives for the people putting the deprecation warnings in those packages don't align with the users of those packages. Their timelines and motives are different.

> In case the sarcasm isn’t clear, it’s better to leave the warts.

And it should be explicitly mentioned in the deprecation warnings.

(You don't want to break systems, but you want something people who care about the system will investigate, and will quickly find and understand the source of and understand what to do.)

Author's point is that their modest proposal (and its sibling, introducing intentional delays in resolving the deprecated API pieces) is a bad idea. Instead, author suggests that making the API change at all is begging the question "Who does this API serve?" It is, perhaps, okay actually if the old system never gets deprecated.

The underlying complaint seems to be about libraries, rather than user behavior.

Then response.getheader should just do that. There is no reason to expose the implementation to the user unless performance is critical.

Two years doesn't seem long to me for a widely used project, unless you have an LTS version that people needing more stability can use, or you are upfront that your API support is two years or less. Of course API support of less than two years is fine, especially for a project that people aren't paying for, but personally I would be quite explicit from the outset (in fact I am with some bits I have out there: “this is a personal project and may change or vanish on a whim, use it in any workflow you depend on being stable at your own risk”). Or am I expecting a bit much there?

If using semver or similar you are fine to break the API at a major release point, that is what a major release means, though it would be preferable for you to not immediately stop all support for the previous major version.

> What if we intentionally made deprecated functions return the wrong result … sometimes?

Hell no. A complete break is far preferable. Making your entire API essentially a collection of undefined (or vaguely undefined) behaviours is basically evil. You effectively render all other projects that have yours as a dependency, also just collections of vaguely defined behaviours. If your API isn't set in stone, say so then people have nothing to complain about unless they specifically ask you to keep something stable (and by “ask you to keep something stable” I mean “offer to pay for your support in that matter”).

> Users that are very sensitive to the correctness of the results…

That is: any user with any sense.

> might want to swap the wrong result for an artificial delay instead.

That is definitely more palatable. A very short delay to start with, getting longer until final deprecation. How short/long is going to be very dependent on use case and might be very difficult to judge: the shortest needs to be long enough to be noticeable to someone paying attention and testing between updating dependencies and releasing, but short enough that it doesn't completely break anything if someone updates and releases quickly, perhaps to bring in a bugfix that has begun to affect their project.

This is still evil, IMO, but a much lesser evil. I'd still prefer the complete break, but then again I'm the sort of person who would pay attention to deprecation notices, so unless you are a hidden nested dependency I'd not be affected.

Does this mean that people and places shouldn't migrate out of older practices? No. But people have different priorities. And sure, we may treat "squeaky wheel policies" as a bad idea, but quite frankly that is far and away the most common policy out there.

To that end, please don't go out of your way to insist that your priority is everyone else's priority.

then remove the function.

Well, removing it earlier would just mean that lots of code would break earlier...

Who cares? This is such a trivial example, where there is no maintenance cost associated with leaving a dummy method in that does a dictionary lookup. I understand there are times when maintenance costs are substantial, but it's hard to take someone seriously when this is their example.

The obsession with newness, and stigmatizing something that doesn't conform to your sense of chasing newness, is really silly.. can you believe it's been deprecated since 2023 and someone still uses it???? 2023 was not some kind of dark ages of distant history.

What I want from code is for it to a) work, and b) if that's not possible, to fail predictably and loudly.

Returning the wrong result is neither of the above. It doesn't draw attention to the deprecation warnings as OP intended--instead, it causes a mysterious and non-deterministic error, literally the worst kind of thing to debug. The idea that this is going to work out in any way calls into question the writer's judgment in general. Why on earth would you intentionally introduce the hardest kind of bug to debug into your codebase?

tl;dr: Stop changing and breaking shit unnecessarily.

Software developers have enough treadmills they need to stay on. Deliberately breaking backward compatibility in the name of "deprecating something old" doesn't have to be one of them. Please don't be that platform or library that deprecates and removes things and makes me have to dust off that old software I wrote in 2005 to move over to a different set of APIs just to keep it working.

I expected this to suggest a tick-tock deprecation cycle, where one version deprecated and the next removed, but this is definitely an idea that belongs on the domain "entropicthoughts.com"