search

epage / clapng

A full featured, fast Command Line Argument Parser for Rust
docs.rs/clap
Apache License 2.0
0 stars 0 forks source link

Deprecate cargo macros #213

Open epage opened 2 years ago

epage commented 2 years ago

Issue by kbknapp Saturday Oct 09, 2021 at 17:32 GMT Originally opened as https://github.com/clap-rs/clap/issues/2840

Please complete the following tasks

Clap Version

3.0.0-beta.4

Describe your use case

I'm proposing removing the convenience macros for getting information from cargo at build time. Specifically:

None of these utilize anything inside of clap and simply call out to checking environment variables that cargo populates at compile time.

Describe the solution you'd like

These would be prime candidates for spinning off into a crate dedicated to such information about Cargo. I'd actually be kind of surprised if a crate with this functionality doesn't already exist. If one doesn't exist, I'm not against hosting one inside the clap-rs org, but being that it's not actually clap related this repository is probably a bad fit.

I propose we deprecate for v3, and remove for v4. That gives us time to either find a crate to suggest or pull these macros into one ourselves.

Alternatives, if applicable

Additional Context

I'm open to suggestions and thoughts on the matter.

epage commented 2 years ago

Comment by pksunkara Saturday Oct 09, 2021 at 18:02 GMT

I would agree but we use them in app_from_crate! and as far as I understand from looking at people creating issues about this part of the code these are really widely used for most the non-popular clis.

epage commented 2 years ago

Comment by kbknapp Saturday Oct 09, 2021 at 18:55 GMT

app_from_crate! could use whatever crate these would get spun off into so I'm not too concerned from that angle.

I'm more worried that because these aren't clap related, what if people want more cargo metadata exposed? These started as just crate_version! but have since grown to a few more. Sure they're not big or complex, but I think they'd fit better into a crate dedicated to that functionality.

I also agree they're pretty widely used which I think adds support to us taking it slow if we move forward (deprecate for a while, remove in a future major release), and also adds support to us creating the crate in our org with an identical API to make the transition painless.

epage commented 2 years ago

Comment by epage Saturday Oct 09, 2021 at 19:15 GMT

I can understand the desire to spin things off. I've wanted arg_enum! in non-clap settings.

I agree that the right route forward is a crate we delegate to but still provide a convenience for clap users.

epage commented 2 years ago

Comment by epage Saturday Oct 09, 2021 at 19:15 GMT

Since a deprecation is not a breaking change, should we move this out of the 3.0 milestone?

epage commented 2 years ago

Comment by pksunkara Saturday Oct 09, 2021 at 19:25 GMT

It is in 3.0 milestone similar to #2835 because we need to add deprecation warnings.

epage commented 2 years ago

Comment by epage Saturday Oct 09, 2021 at 19:29 GMT

We should not be deprecating anything without having a replacement to point people towards. Unless we are creating the crate now, we shouldn't do this.

With #2835, we have replacements (builder, derive, from usage) that we can point people to as the recommended approach.

epage commented 2 years ago

Comment by kbknapp Sunday Oct 10, 2021 at 01:08 GMT

Since a deprecation is not a breaking change, should we move this out of the 3.0 milestone?

Good point. My point was just to deprecate for 3.0 like @pksunkara mentioned, but you're correct we could deprecate anywhere in the 3.x lifetime. I'll place this at the 3.1 milestone as a placeholder for "decide on this sometime in 3.x"

And of course we're not locked into spinning these out, I'm open to suggestions and opinions on the matter too.

epage commented 2 years ago

Comment by joshtriplett Monday Oct 11, 2021 at 09:29 GMT

I think it'd be perfectly reasonable to just make these non-public before 3.0, as long as the top-level app_from_crate macro still exists.

I don't think we have to provide a replacement first. These macros just existed to pass to the appropriate clap functions.

epage commented 2 years ago

Comment by epage Monday Oct 11, 2021 at 14:05 GMT

I think it'd be perfectly reasonable to just make these non-public before 3.0, as long as the top-level app_from_crate macro still exists.

For context, I'm recommending in https://github.com/clap-rs/clap/issues/2617 that we provide built-in transition paths for users via deprecations to streamline the upgrade process. We can do breaking changes but ideally we have a deprecation windows first

epage commented 2 years ago

Comment by pksunkara Monday Oct 11, 2021 at 14:10 GMT

I think it'd be perfectly reasonable to just make these non-public before 3.0, as long as the top-level app_from_crate macro still exists.

IIRC, people actually use those underlying macros directly instead of app_from_crate! and created some issues around them.