Create a dedicated documentation section on StructOpt migration

[nyurik]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

3.0.14

Describe your use case

Clap has great documentation, but for those migrating from structopt it might be a bit challenging to find all the relevant bits between FAQ, Release notes, and other sources. I have looked at them, including discussions, and they tend to have many unrelated v2->v3 and other details. Release notes tend to get burred over time, especially when not linked directly. Structopt users will always have an unchanged version of structopt (as it is no longer updated) that needs to be migrated. Thanks!

Describe the solution you'd like

Please add a dedicated structopt section to the documentation page that succinctly gives minimum required steps to migrate latest structopt usage to clap v3 (or whatever the latest would be).

Alternatives, if applicable

No response

Additional Context

No response

[epage]

Leaving aside the release notes being buried over time, what were you finding lacking in our migration guide?

• You mentioned v2->v3 migration but that is necessary because you have to do them together

[nyurik]

@epage I understand that clap migrated v2->v3 and as part of that migration introduced structopt-like functionality (yay!!). My point is that many users who use structopt would not be aware of this migration due to never using clap directly. I just did a (small) migration, and would have found the following information useful. This is by no means complete guide, but I have had to research some of them in several places, so might be useful to others, perhaps as a two column table.

StructOpt Migration Guide

• In Cargo.toml, replace structopt = "0.3.26" dependency with clap = { version = "3.0.14", features = ["derive"] }
• Replace use structopt::StructOpt; with use clap::Parser as StructOpt;, or replace all #[derive(StructOpt)] usages with #[derive(Parser)]
• [Optional] Replace #[structopt(...)] with #[clap(...)] (TBD: I have no idea why both still work, and if its intentional)
• Replace Opt::from_args() with Opt::parse(), where Opt is the top level options struct.
• Remove arg_enum! { enum { ... } } wrapper, replacing it with #[derive(ArgEnum)] enum { ... }. At the enum usage in a struct, remove possible_values and case_insensitive structopt params, and use #[clap(arg_enum)] instead.

[epage]

My point is that many users who use structopt would not be aware of this migration due to never using clap directly.

Yes, aside from the question on where it should live or how to discover it, I was trying to understand what you found lacking in our existing migration guide because you alluded to several problems with it.

(TBD: I have no idea why both still work, and if its intentional)

We tried to favor deprecations over hard breaking changes:

• StructOpt is an alias for Parser
• • #[structopt] maps to #[clap]
• Parser also includes from_args.
• arg_enum! still exists

[epage]

I have added a link to our migration guide to our FAQ and have opened a PR to add a link from structopt's README.

[nyurik]

My point is that many users who use structopt would not be aware of this migration due to never using clap directly.

Yes, aside from the question on where it should live or how to discover it, I was trying to understand what you found lacking in our existing migration guide because you alluded to several problems with it.

I think my biggest concern with it is that it is in the release notes vs readme, and so it won't be maintained as an ongoing documentation in a single location. Clap will certainly change with time, but people may decided to migrate from their existing well-working StructOpts at any time, possibly in some future when release notes won't be as up to date.

(TBD: I have no idea why both still work, and if its intentional)

We tried to favor deprecations over hard breaking changes:

• StructOpt is an alias for Parser
• • #[structopt] maps to #[clap]
• Parser also includes from_args.
• arg_enum! still exists

My IDE shows deprecations as crossed-out, so I changed them right away and thought it would be a good idea to include them in the migration guide. I think migration should be done towards the non-deprecated features so as not to revisit them again soon.

Once again, thanks for all the hard work, absolutely love the project, just trying to help newcomers get started quicker :)

[epage]

I think my biggest concern with it is that it is in the release notes vs readme, and so it won't be maintained as an ongoing documentation in a single location. Clap will certainly change with time, but people may decided to migrate from their existing well-working StructOpts at any time, possibly in some future when release notes won't be as up to date.

I was thinking about this and I think it shouldn't be a living document. As we diverge further from clap2, the worse it will be both for the user and for us to document. We also then have to decide at what point in the long tail we cut people off and stop updating it. Instead, I think its best for people to migrate to clap v3 first and then to any future version.

My IDE shows deprecations as crossed-out, so I changed them right away and thought it would be a good idea to include them in the migration guide. I think migration should be done towards the non-deprecated features so as not to revisit them again soon.

It was a very intentional choice to leave deprecations to the end and more as a foot note. There are a lot of subtle behavior changes and we wanted the user to focus on those and not all of the mechanical changes.

[epage]

As we have a dedicated migration guide, written to accomplish specific goals, and it is now more discoverable, I'm going to go ahead and close this.

[dmitris]

to note the "structopt migration guide" link on https://docs.rs/clap/4.1.4/clap/_faq/index.html#how-does-clap-compare-to-structopt pointing to https://docs.rs/clap/4.1.4/clap/CHANGELOG.md#migrate-structopt is bad/stale ("The requested resource does not exist"). Do you know the current location, by any chance? /cc @epage

[epage]

See https://github.com/clap-rs/clap/blob/v3-master/CHANGELOG.md#migrating

Looks like we link to it from structopt's pinned issue and the README but not docs.rs. That would be a worthwhile improvement.

[Croug]

I wanted to mention that https://docs.rs/clap/latest/clap/_faq/index.html#how-does-clap-compare-to-structopt still gives bad resource when trying to click on the link to the migration guide, I believe this should be resolved as the faq is always in the first couple links when trying to find information around migrating from structopt to clap derive.

[epage]

... wow they clearly said the link was bad and I somehow overlooked that. The link should be fixed in 4.4.13

[Croug]

Happens to the best of us 😂, thanks for the quick response!

[RReverser]

FWIW the "Documentation parity" link on https://docs.rs/clap/latest/clap/_faq/index.html#how-does-clap-compare-to-structopt is still broken.

[epage]

Missed that one. Not as needed anymore, so I removed it.