Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Potentially Upcoming Minor Breaking Change #808

Closed
5 of 9 tasks
kbknapp opened this issue Jan 5, 2017 · 0 comments
Closed
5 of 9 tasks

Potentially Upcoming Minor Breaking Change #808

kbknapp opened this issue Jan 5, 2017 · 0 comments
Assignees
@kbknapp
Labels
M-breaking-change Meta: Implementing or merging this will introduce a breaking change.

Comments

@kbknapp
Copy link
Member

kbknapp commented Jan 5, 2017 •
edited
Loading

(Note: Those who already responded in the PR, need not repeat there answer. I'm simply moving the discussion to allow progress without breaking code 😉)

Proposed Minor Breaking Change in an upcoming release

There is a very minor breaking change that I'd like to make in an upcoming release without bumping the major version. Why is the major version not bumped? The following items:

  • it's to fix a bug in the original code
    • the fix is very beneficial to users of said feature
  • the fix for users is trivial and not always required
  • it's a niche feature

Details: App::write_help would require &mut self instead of &self. This allows the App::write_help to actually print the true and full help message, which isn't happening currently. That's it.

This means if you use

let app = /* .. */;
app.write_help(/* .. */);

Change your code to:

let mut app = // all else remains the same

Note mut app.

However, if you used

let app = // no semi-colon
    .write_help(/* .. */);

No change is required

A search on github found the following users of said feature. Please respond if you have objections to this release (specifically the change to your code when using App::write_help).

Relates to #801
@kbknapp kbknapp added M-breaking-change Meta: Implementing or merging this will introduce a breaking change. T: RFC / question labels Jan 5, 2017
@kbknapp kbknapp self-assigned this Jan 5, 2017
This was referenced Jan 5, 2017
Closed
Closed
@kbknapp kbknapp changed the title Upcoming Minor Breaking Change Potentially Upcoming Minor Breaking Change Jan 5, 2017
kbknapp added a commit that referenced this issue Apr 5, 2017
@kbknapp
api: adds new App method calls for printing and writing the long vers…
d82b4be 
…ion of help messages

One can now use `App::print_long_help` or `App::write_long_help`

Note that `App::write_long_help` is **NOT** affected by #808 in the manner
that `App::write_help` help is and thus should be preferred if at all possible.
@kbknapp kbknapp closed this as completed Oct 4, 2017
kbknapp added a commit that referenced this issue Jan 24, 2018
@kbknapp
fix(Help): fixes an issue where help is not properly written using Ap…
4f3231a 
…p::write_help

Contains a *MINOR* breaking change. App::write_help now requires `&mut self` instead of `&self`.

This fixes a major bug where the help message is entirely incorrect.
More can be found at #808

I've decided to make this change because it was preventing further progress.

Anyone's code who breaks the fix is trivial:

```rust
// OLD BROKEN
let app = App::new("broken");
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");

// NEW FIX
let mut app = App::new("broken");  // <-- let mut
let mut out = io::stdout();
app.write_help(&mut out).expect("failed to write to stdout");
```

Closes #808
@kbknapp kbknapp mentioned this issue Jan 31, 2018
Closed
87 tasks
kbknapp added a commit that referenced this issue Jan 31, 2018
@kbknapp
depr(App.rs): deprecates old App methods in prep for v3
c441467 
A full list of deprecations is:

* App::version_message -> App::mut_arg
* App::version_short -> App::mut_arg
* App::help_message -> App::mut_arg
* App::help_short -> App::mut_arg
* App::from_yaml -> serde
* App::usage -> App::override_usage (+no longer assumes leading \t)
* App::help -> App::override_help
* App::template -> App::help_template
* App::args_from_usage -> App::args(&str)
* App::arg_from_usage -> App::arg(Arg::from)
* App::write_help -> &self -> &mut self (#808)
* App::gen_completions -> clap_completions::generate
* App::gen_completions_to -> clap_completions::generate_to
* App::get_matches_safe -> App::try_get_matches (#950 Lib Blitz naming
consistency)
* App::get_matches_from_safe -> App::try_get_matches_from (#950 Lib Blitz
naming consistency)
* App::get_matches_safe_borrow -> App::try_get_matches_from_mut (#950 Lib
Blitz naming consistency)
This was referenced May 13, 2020
Closed
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@kbknapp kbknapp

Labels
M-breaking-change Meta: Implementing or merging this will introduce a breaking change.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@kbknapp