Feat: Deprecate warnings

[Tieske]

based on discussion here: #285 (comment)

[alerque]

I assume the idea here is only to do nothing by default until the next major release (and override for our own testing), but starting in the next major release we will start throwing our internal deprecation warnings by default (and let people override to disable), correct?

[Tieske]

Not sure, see the note regarding overriding this function in applications, not in libraries. I think it might be better to not have a default implementation, and upon a release that removes stuff add a proper warning to the change log.

Just to make sure we do not accidentally break (other peoples) stuff.

[alerque]

I don't think there is any use is having a deprecation warning feature that is off by default and people have to define a function to get access to it. Half the point is to ease the pain of upgrades for people that aren't paying any attention to them at all! Especially if the dependency for their project is indirect, there is no way an appreciable percentage of users are going to set up a deprecation warning catcher in their systems. What we want to do is warn them before their stuff breaks unexpectedly. In order to do that this must be on by default. Yes that might break a few people's setups if they relly on STDERR streams for some reason to function, but that's a lot less people than will be caught by unexpected deprecations they didn't have time to plan for because they never saw messages and don't read release notes closely for all dependencies.

Waiting until a major version to possible break STDERR by introducing these warnings is one thing, not enabling them by default ever is another (and I think nearly defeats the utility).

But yes, other libraries should never override this, apps may if they want to and do so intentionally. After that the onus is on them to update their old code or not update to a breaking release.

[Tieske]

Half the point is to ease the pain of upgrades for people that aren't paying any attention to them at all

That's a usecase for SemVer, not having to worry about it. But considering SemVer, we should not be breaking anything unless it is on major bump.
Generating additional output that wasn't there before breaks that promise. And hence might break stuff on minor or even patch releases.

So it would effectively mean that deprecation messages can only be added on major versions. That is also a very slow moving process which I'd like to avoid.

So effectively we can try to;

• make users move fast, and Penlight slow
• move Penlight fast, and let users deal with their own issues, whilst we provide the instruments

imo betting on other people to do what you want them to do usually doesn't work. Also the folks not paying attention are most likely also the ones that simply disable the warnings and move on.

[alerque]

Generating additional output that wasn't there before breaks that promise.

I don't think changing the exact content of the STDERR stream output to add new warnings will be breaking a promise, only the position we are in now where we are changing what channels we do or don't output anything at all on is a breaking change (going from not using STDERR to using it for warnings). In this case I think the new promise for 2.0.0 and later is that STDERR is something Penlight can and will sometimes write warnings too. After that we're free to add new upcoming deprecation notices on whatever timeline we like as they come up and do the actual breaking removals on major releases.

People that disable warnings and move on and don't read changelogs can take care of themselves when something breaks. I have no pity for that. What I do what is a clear mechanism by which they would have been warned by default if they didn't explicitly choose their own adventure.

[Tieske]

I have a long history of breaking stuff in unexpected ways, because I assumed it would be fine. With #346 being the latest one in that chapter. Also at Kong we've had many problems from automatic version bumps on minor or patch level before, imo we should not risk breaking anything.

From a scoping perspective; the problem of downstream projects keeping in sync or falling behind on Penlight versions, is not a Penlight problem to solve.

So far in this discussion I changed my mind from not sure to a firm no. @hishamhm what is your opinion on this? input appreciated.

@alerque wrt this PR, code ok for pre-2.0.0?

[alerque]

My opinion is firming up too — in the opposite direction! 😋

In the meanwhile I don't see anything in here that is a problem to merge pre-2.0.0. Since we at least both agree that we can't start enabling warnings on a hitherto unused IO channel before 2.0.0 anyway this is the way the code needs to be until then.

Only when releasing 2.0.0 should we announce what our promise is: either to never add or change deprecation warning messages on STDERR except on major releases (your way, requires 2 major releases for every deprecation, one to announce future deprecation and one to actually do it) OR to clarify that STDERR can and will be used by default for new deprecation warnings on minor releases announcing upcoming major versions but can be handled via the override function as well (my way, requires 1 major release bump when actual breaking change takes place).

[Tieske]

your way, requires 2 major releases for every deprecation, one to announce future deprecation and one to actually do it

no, that's not what I'm advocating. Options so far are;

1. do not add a default warning mechanism, deprecate in major, minor, even patch. Removal is on the next major. This allows Penlight to move fast.
2. add a default warning mechanism, but deprecate only on major. Removal is on next major. This is slow moving.
3. add a default warning mechanism. Deprecate in major, minor, even patch. Removal is on next major. This is also fast moving for Penlight.

My preferred option is 1, yours is 3 if I'm correct.

1 and 2 are safe imo, 3 requires to exclude the stderr output from the versioning scope (to be SemVer compliant)