clap-rs / clap

A full featured, fast Command Line Argument Parser for Rust

docs.rs/clap

Apache License 2.0

13.65k stars 1.02k forks source link

Write-up of opt-in deprecation warnings? #5422

Closed svix-jplatte closed 3 months ago

svix-jplatte commented 3 months ago

Hi, I just went through https://github.com/clap-rs/clap/issues/3822 and other related GitHub / reddit threads to find a summary of the opt-in deprecation scheme that clap ended up with. Is my memory serving me wrong that such a write-up exists?

epage commented 3 months ago

Are you looking for justification for it, an explanation of the mechanics / pattern, or user facing "how to opt-in"?

svix-jplatte commented 3 months ago

Mostly an explanation of the pattern (I think there's not much to it, simple cfg-gated deprecation attributes?), probably with the motivation as an introduction. I thought I saw something like that before 😅

Context: wanted to link to it as prior art when mentioning the pattern for another project.

epage commented 3 months ago

3830 is the main place I can think of which is linked to in the above. That included updates to our compatibility documentation and shows how we did this. One of the key things that requires extra work is when proc-macros need to call deprecated functionality.

svix-jplatte commented 3 months ago

Okay, so I guess I was imagining that there was a separate document / article about this pattern. Thanks :smile: