Skip to content

Commit

Permalink
Pin clap to v3.1 to avoid surprising deprecation warnings
Browse files Browse the repository at this point in the history 
I'd rather not have to deal with the new API because there is no problem
with the old one for me.

Once 4.0 becomes the default, the work has to be put in to probably
achieve the same, but I hope it's not more wordy than before.
I also hope that inconveniences will be figured out by the folks in the
mean time.

Related to clap-rs/clap#3822
  • Loading branch information
@Byron
Byron committed Jun 14, 2022
1 parent f6c2f94 commit ac05284
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 11 deletions.
20 changes: 10 additions & 10 deletions Cargo.lock
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
View file
Expand Up @@ -88,7 +88,7 @@ git-repository = { version = "^0.19.0", path = "git-repository", default-feature

git-transport-for-configuration-only = { package = "git-transport", optional = true, version = "^0.18.0", path = "git-transport" }

clap = { version = "3.0.0", features = ["derive", "cargo"] }
clap = { version = "~3.1.0", features = ["derive", "cargo"] }

This comment has been minimized.

Sign in to view

Copy link
@epage

epage Jun 15, 2022

Contributor

This can now be reverted as deprecations are now off by default, see clap-rs/clap#3830 for details. When you do start working through the deprecations as part of upgrading to 4.0, we've also improved the warnings for derive users. See clap-rs/clap#3832 for examples.

btw How come you needed to pin it in the Cargo.toml when the Cargo.lock already pins it for you?

This comment has been minimized.

Sign in to view

Copy link
@Byron

Byron Jun 16, 2022

Author Owner

Thanks for the heads-up, it's much appreciated! I have updated to the most recent version in aaf1cde and understand deprecation warnings might be turned on in a future minor release by making deprecated a default feature.

Personally I'd love if that didn't happen so people who want to start the upgrade can do so on their own terms, rather than being nudged after a cargo update (this is no critique btw, just something that would work best for me).

Speaking of, I run cargo update from time to time to control version updates, and that's why I sometimes have to pin versions in Cargo.toml if I want to be sure the next cargo update doesn't fetch undesirable versions.

Just to share some thoughts, I was carefully watching what was going on around the 'deprecation release' and found the way you dealt with it commendable. I can only imagine how hard you worked to course-correct to the point where clap is now. Thanks for that!
I also learned a lot about the potential issues with deprecation and hope to derive a workflow for adoption by gitoxide. For now I am leaning towards adding deprecations behind a feature toggle which is advertised in the changelogs, but won't ever be activated by default. It's merely a service people can use to facilitate an upgrade. As opposed to a version bump, it will probably be available early on and more deprecations can be added over time.

This comment has been minimized.

Sign in to view

Copy link
@epage

epage Jun 16, 2022

Contributor

Personally I'd love if that didn't happen so people who want to start the upgrade can do so on their own terms, rather than being nudged after a cargo update (this is no critique btw, just something that would work best for me).

To be clear, this is all iterative learning and I might change this over time. I'm concerned that leaving it off by default will leave behind those users who do not read blog posts or changelogs and blindly upgrade across breaking changes, as I observed with clap 3.0. Those users who want to hold back can can still do so by disabling default features to turn deprecations back off. Its a pain because you can't subtract features but maybe its the kind of pain that nudges people to move along? Who knows.

One element I left out of the post mortem I posted was that I expected to have less immediate impact due to lock files since clap is target at programs which tend to use them. I forgot how many libs are around that still pull in clap for helper tools.

I also learned a lot about the potential issues with deprecation and hope to derive a workflow for adoption by gitoxide. For now I am leaning towards adding deprecations behind a feature toggle which is advertised in the changelogs, but won't ever be activated by default. It's merely a service people can use to facilitate an upgrade. As opposed to a version bump, it will probably be available early on and more deprecations can be added over time.

This is giving me more confidence in wanting to find some way of communicating out clap's approach. I had meant to propose a RustConf topic on it but never got around to it. I'd like to find an appropriate evergreen documentation to put it in. Not to say every project has to do it exactly but where is a toolset and people pick the parts that fit with the scale of their project.

This comment has been minimized.

Sign in to view

Copy link
@Byron

Byron Jun 16, 2022

Author Owner

Thanks for sharing your insights, I will be sure to adjust the stability guide to define how to deal with deprecations, in time and hope to learn from claps experience. As gitoxide aims to come with default features leaving users with git-repository = "1" in their Cargo.toml files, deprecations wouldn't be allowed to become default as it forces an opt-out of a surprise. With clap however I always found myself to configure features (makes sense), so there adding deprecations to default features at some point should be no issue for most.

[…] and blindly upgrade across breaking changes, as I observed with clap 3.0.

That's quite surprising, as it implies an unawareness of how semver works to the point of opening issues. I plan to allow for major releases every half a year, so hopefully users will learn from that should they chose to upgrade. After initial 1.0 stabilization this also means there might be some breaking changes regularly, until it all settles and there will be less of that. Also I hope that for every breaking change, there is substantial improvements coming with it or at least fixes which wouldn't be possible otherwise.

I'd like to find an appropriate evergreen documentation to put it in.

I endorse that - ultimately it's about alignment which can make deprecations unsurprising if people know how to deal with it. After a while, it's going to be part of the common knowledge or culture even.
prodash = { version = "19.0.0", optional = true, default-features = false }
atty = { version = "0.2.14", optional = true, default-features = false }
env_logger = { version = "0.9.0", default-features = false }
Expand Down

0 comments on commit ac05284

Please sign in to comment.