Deprecate cargo macros

[epage]

Issue by kbknapp
Saturday Oct 09, 2021 at 17:32 GMT
Originally opened as clap-rs/clap#2840

---

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

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:

• crate_license
• crate_version
• crate_authors
• crate_description
• crate_name

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

• We keep these macros unchanged as they're small and self contained

Additional Context

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

[epage]

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]

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]

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]

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]

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]

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]

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]

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]

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 clap-rs/clap#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]

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.