Bug 618154 - Make documentation of localupdate and localinstall options consistent
Make documentation of localupdate and localinstall options consistent
Status: CLOSED UPSTREAM
Product: Fedora
Classification: Fedora
Component: yum (Show other bugs)
13
All Linux
low Severity medium
: ---
: ---
Assigned To: Seth Vidal
Fedora Extras Quality Assurance
: Reopened
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2010-07-26 05:36 EDT by Kamil Páral
Modified: 2014-01-21 18:16 EST (History)
7 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2010-10-04 13:13:48 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Kamil Páral 2010-07-26 05:36:28 EDT
Description of problem:
"yum localupdate" is documented in man page, but it is not documented in yum --help nor it is offered with bash completion.

Version-Release number of selected component (if applicable):
yum-3.2.27-4.fc13.noarch
yum-presto-0.6.2-1.fc13.noarch
yum-plugin-changelog-1.1.27-2.fc13.noarch
yum-metadata-parser-1.1.4-1.fc13.x86_64
yum-plugin-downloadonly-1.1.27-2.fc13.noarch
yum-utils-1.1.27-2.fc13.noarch

How reproducible:
always

Steps to Reproduce:
1. yum --help
2. yum local[TAB] (with bash-completion enabled)
3.
Comment 1 seth vidal 2010-07-26 10:49:53 EDT
 more or less a duple of 616414 - see that bug for an explanation.

*** This bug has been marked as a duplicate of bug 616414 ***
Comment 2 Andre Robatino 2010-07-27 11:06:55 EDT
In the latest Rawhide yum (yum-3.2.27-20.fc14.noarch), my original bug 616414 (mentioning the legacy nature of localinstall and localupdate in yum's man page) is fixed, but this bug still isn't.  So please reopen this bug (and probably change the Subject to something like "remove localupdate from --help").
Comment 3 seth vidal 2010-07-27 11:16:49 EDT
we won't be removing localupdate and I'm not enamored of putting it in the bash completions.

So. no on reopening this bug.
Comment 4 Kamil Páral 2010-07-27 11:52:51 EDT
Seth, I believe Andre wanted to say that it would be nice to have the options consistent. Both "localinstall" and "localupdate" should be in a man page, or neither one. Both should be in --help, or neither one. Both should be in bash completion, or neither one.

Currently it is very inconsistent (localinstall is in --help and bash completion and localupdate isn't).

Since that stuff is obsoleted, reasonable solution would appear to me like this:
* both documented in page (with obsoletion remark)
* neither available in --help (let's not encourage new users to use it)
* neither available in bash completion (same reason)

Does that make sense, Seth?
Thanks.
Comment 5 Andre Robatino 2010-07-27 12:01:56 EDT
Correction to comment 2: A better Subject would be "localinstall should be removed from --help and bash completion".
Comment 6 Andre Robatino 2010-07-27 21:21:40 EDT
In F13, using yum-3.2.27-4.fc13.noarch, with the bash-completion package installed:

[root@compaq-pc ~]# yum --help | grep local
localinstall   Install a local RPM

while "yum local[TAB]" returns just "localinstall".

In Rawhide, using yum-3.2.27-20.fc14.noarch, with the bash-completion package installed:

[root@localhost ~]# yum --help | grep local
localinstall    Install a local RPM

while "yum local[TAB]" returns both "localinstall" and "localupdate".

Kamil, please reopen this bug and change the Subject line accordingly (to something like "remove localinstall and localupdate from --help and bash completion").  You might want to change the Version to rawhide, since the bug still exists there (although the behavior is slightly different).  Thanks.
Comment 7 Andre Robatino 2010-07-27 21:30:41 EDT
F12 with yum-3.2.27-3.fc12.noarch behaves exactly the same as F13 above.
Comment 8 Kamil Páral 2010-07-28 09:56:27 EDT
Ok, reopening the bug.

The request is now not about removing/adding some option somewhere - let the maintainers think out the best way. The request is now to make localupdate and localinstall options documentation consistent (in man page, in --help, in bash completion). Both should be mentioned in one place, or neither of them should.

Thanks.
Comment 9 Andre Robatino 2010-07-28 11:25:05 EDT
Is there a standard policy for where legacy options (options that exist just so old scripts don't break) should be documented (or not documented)?  I think there ought to be.
Comment 10 Andre Robatino 2010-07-30 14:49:52 EDT
Just noticed that bash completion (after installing the bash-completion package) on a local file works properly when using "localinstall" or "localupdate", but not when using "install",  "update", or "downgrade".  Should this be considered a bug, and if so, which component should it be reported under (yum or bash-completion)?
Comment 11 Andre Robatino 2010-08-01 11:14:12 EDT
Never mind, I see that yum handles its own bash completion in /etc/bash_completion.d/yum.bash, so the issue in comment 10 should probably be considered part of this bug.
Comment 12 Ville Skyttä 2010-10-04 13:06:59 EDT
(In reply to comment #8)
> The request is now not about removing/adding some option somewhere - let the
> maintainers think out the best way. The request is now to make localupdate and
> localinstall options documentation consistent (in man page, in --help, in bash
> completion). Both should be mentioned in one place, or neither of them should.

My humble opinion: no need to be ultra consistent, IMO we can do better; leave them in man page which is the place where the most in-depth documentation is, and drop them from other more concise docs (and the like) due to their deprecated nature.

- Leave man page as is (both documented with obsoletion notes).
- Remove both from --help (only localinstall is there at the moment).
- Remove both from bash completion's suggested commands, but leave the
  proper completion functionality for them in case someone uses them anyway.

(In reply to comment #10)
> Just noticed that bash completion (after installing the bash-completion
> package) on a local file works properly when using "localinstall" or
> "localupdate", but not when using "install",  "update", or "downgrade".

Fixed in git now: http://yum.baseurl.org/gitweb?p=yum.git;a=commitdiff;h=3ff6f41
Comment 13 Kamil Páral 2010-10-04 15:56:12 EDT
(In reply to comment #12)
> My humble opinion: no need to be ultra consistent, IMO we can do better; leave
> them in man page which is the place where the most in-depth documentation is,
> and drop them from other more concise docs (and the like) due to their
> deprecated nature.
 
Thanks Ville, that was exactly what I asked for :)
Comment 14 Ville Skyttä 2010-10-05 02:11:20 EDT
(In reply to comment #13)
> Thanks Ville, that was exactly what I asked for :)

Oh, believe it or not I did miss comment 4 before writing comment 10, scary coincidence and similarity :)

Note You need to log in before you can comment on or make changes to this bug.