Bug 1573154

Summary: man page does make clear command is not optional
Product: Red Hat Enterprise Linux 7 Reporter: Stephen Wadeley <swadeley>
Component: yumAssignee: Packaging Maintenance Team <packaging-team-maint>
Status: CLOSED ERRATA QA Contact: Luca Berton <lberton>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 7.4CC: james.antill, lberton, mdomonko
Target Milestone: rcKeywords: Triaged
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: yum-3.4.3-166.el7 Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2020-03-31 20:03:32 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On:    
Bug Blocks: 1630909    

Description Stephen Wadeley 2018-04-30 11:15:12 UTC
Description of problem:

Reading the man page too briefly can lead you to believe that this is a valid command:

yum --disablerepo=<repo> check-update

as happened here:
https://bugzilla.redhat.com/show_bug.cgi?id=689208#c1

Version-Release number of selected component (if applicable):

~]# rpm -q yum
yum-3.4.3-154.el7.noarch

How reproducible:


Steps to Reproduce:
1. man yum


Actual results:

SYNOPSIS
       yum [options] [command] [package ...]


Expected results:

SYNOPSIS
       yum [options] COMMAND [package ...]



Additional info:

The text for the man page can be improved in other places. Happy to send patches.

Comment 3 Michal Domonkos 2018-11-26 10:17:06 UTC
(In reply to Stephen Wadeley from comment #0)
> Description of problem:
> 
> Reading the man page too briefly can lead you to believe that this is a
> valid command:
> 
> yum --disablerepo=<repo> check-update

Actually, this *is* a valid command.  What's not valid is something like:

yum --disablerepo=<repo>

That's what the reporter of the other BZ did with the expectation that it would disable the repo permanently, which is incorrect.

OTOH, it's true that the man page section for --disablerepo only says the following:
"Disables specific repositories by id or glob."
This can, indeed, mislead new users into thinking that it can be used alone, without a command, to permanently disable the given repo.

> Steps to Reproduce:
> 1. man yum
> 
> 
> Actual results:
> 
> SYNOPSIS
>        yum [options] [command] [package ...]
> 
> 
> Expected results:
> 
> SYNOPSIS
>        yum [options] COMMAND [package ...]

OK, this is a valid change that should make things clearer so we'll consider it.

> Additional info:
> 
> The text for the man page can be improved in other places. Happy to send
> patches.

Here's the upstream repo:
https://github.com/rpm-software-management/yum

Patches are, of course, welcome, however please keep in mind that we cannot accept big changes (not even to the man page) at this point.  In any case, feel free to post them and we'll take a look.  Thanks!

Comment 4 Stephen Wadeley 2019-04-17 08:49:35 UTC
Hello

Sorry for very long delay

https://github.com/rpm-software-management/yum/pull/88


Thnak you

Comment 5 Michal Domonkos 2019-06-19 14:37:54 UTC
(In reply to Stephen Wadeley from comment #4)
> Hello
> 
> Sorry for very long delay
> 
> https://github.com/rpm-software-management/yum/pull/88
> 
> 
> Thnak you

I don't think we should make the second change ("Temporarily enable ..."). To stay consistent, we would then have to add "temporarily" to every single CLI option as well.  If there's no customer ticket related to this specifically, I would just leave it as it is.  There's power in simplicity and consistency.

Regarding the first change, that's completely valid and we can use that.

Comment 6 Stephen Wadeley 2019-06-19 14:47:40 UTC
Hello

OK to comment 5, 

let me know if I need to make another push to remove that commit.

Thank you

Comment 7 Michal Domonkos 2019-06-19 14:54:55 UTC
I just did. Thanks!

Comment 12 errata-xmlrpc 2020-03-31 20:03:32 UTC
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2020:1122