[Proposal] `as: level` for deprecrated attribute

[Bryan Paxton]

 It's often the case that a project values using `--warnings-as-errors`, yet the `deprecation` attribute conflicts with this option, in that it may be some time before a function gets hard deprecated. What's more, the function might be utilized across many modules such that it's not reasonable nor safe to update all modules all the same time.

After discussing this issue with Scott Southworth, we ended up with what seemed like a useful addition to `deprecated` attribute, an `:as` option that takes a log level argument. 

This conceivably would ease the adoption process of updated libraries that have soft deprecated functions or modules. This would allow a library author to set the deprecation to log level to `:notice` (as an example). When a "stronger" deprecation is deemed advantageous, library authors can change this to warning, and perhaps lib authors may even opt to switch to the error level before completely removing a function (though, how useful that would be is not clear).

This has been discussed in the past I do believe, but iirc it was around filtering specific warnings from specific deps vs an extension to the `deprecated` attribute. 

Cheers.

[Kip]

A few thoughts, only to aid the conversation:

1. As a library writer I do feel the need to ensure compiler warnings are eradicated during the RC cycle of the next Elixir release.  While this definitely puts pressure on me (Im maintaining around 40 libs at the moment), it does act as a strong motivator to keep up-to-date and minimise DX issues for consumers.  I'm not sure I would trust myself to just lower the log level and never come back.

2. We do already have the hard deprecation `@deprecated` and soft deprecation `@doc deprecated: "Some deprecation notice"`. Do you not think that caters for much of what you propose? See https://hexdocs.pm/elixir/1.15.4/writing-documentation.html#documentation-metadata Yes, I appreciate they both still emit warning messages, but only one of them halts compilation with `--warnings-as-errors`.

[Bryan Paxton]

 On point 1: 
    
That is fair and gives me pause. I'm interested in the scenario though. You seem to be suggesting that per an elixir lang deprecation you would have to adjust the level on in many of your libs? I'm not sure such a feature would be used by elixir itself, but you make a good point none the less. It also gives me pause in regard to the "too many options" problem.  What is there now, is simple, that can not be denied.

On point 2 :
   
So, arguably the hard deprecation is not a hard deprecation and is in fact a soft deprecation, this is why I used the language "stronger" deprecation, but I hear your point.  FWIW,  I consider a hard deprecation a removal or something that explicitly results in an error, thus preventing compilation regardless of flags passed to the compiler. This is indeed where things get a bit odd. As far as emitting warnings in docs and change-logs vs the console via the doc option, I do like this myself,  yet it does force your hand if you want or need to update a dep immediately. You are left with two options : turn off warnings-as-errors, which is terribly unappealing or update potentially hundreds of files at once, which is never a good idea IMHO. FWIW,  the concern I've seen raised is around it simply not being noisy enough, that is emitting doc depreciation for a while.  Noise is sometimes useful.

Both of your thoughts have given me pause and make me think that there is perhaps a better solution, and maybe even there's nothing to solve fo, although I am still terribly interested in being more polite in regard to depreciation though :) . We should all read docs and change-logs, and even better source code. However, I think it behooves the community to think about making a deprecation as widely "accessible" as possible. This conversation is also pointing the fact, that perhaps a lot of us are holding --warnings-as-errors wrong, or rather holding it because it's the only thing we have to hold in the spirit of safety :)

This also points to the fact that perhaps there needs to be more granularity around --warnings-as-errors, which is not something elixir can change itself. In fact, now that I think about it and without looking, I do believe the deprecation attribute augmentation I'm proposing also must be adjusted in erlang first. It is good to reach out to the people here to get a discussion going though.
 
I'll perhaps look to proposing this on the erlang forums and see what thoughts are there as well.

[Wojtek Mach]

This is fairly specialized scenario so I’d go with a specialized solution. How about this: do your build in a build.sh, compile without warnings as errors however in the script inspect stderr and fail on a "warning: " unless that warning is for a deprecation. Hopefully fairly straightforward regexps would suffice (now you have N+1 problems nonwithstanding). Less complexity in the toolchain, less churn for maintainers (as they’d have to use the suggested :as annotation), and more control to you, make the script as simple or as complicated as you need it to be.

Wiadomość napisana przez Kip <kipc...@gmail.com> w dniu 21.11.2023, o godz. 00:45:

A few thoughts, only to aid the conversation:

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/0579affe-a9b2-4e50-bd81-b47962b7356dn%40googlegroups.com.