Issue #14200 has been updated by Chris Price.
Pardon the verbosity... but, for posterity and transparency, I want to record
an example output from the old version vs. the new version.
Old version:
Usage: puppet <subcommand> [options] <action> [options]
Available subcommands, from Puppet Faces:
ca Local Puppet Certificate Authority management.
catalog Compile, save, view, and convert catalogs.
certificate Provide access to the CA for certificate management.
certificate_request Manage certificate requests.
certificate_revocation_list Manage the list of revoked certificates.
config Interact with Puppet's configuration options.
facts Retrieve and store facts.
file Retrieve and store files in a filebucket
help Display Puppet help.
instrumentation_data Manage instrumentation listener accumulated data.
instrumentation_listener Manage instrumentation listeners.
instrumentation_probe Manage instrumentation probes.
key Create, save, and remove certificate keys.
man Display Puppet manual pages.
module Creates, installs and searches for modules on the
Puppet Forge.
node View and manage node definitions.
parser Interact directly with the parser.
plugin Interact with the Puppet plugin system.
report Create, display, and submit reports.
resource API only: interact directly with resources via the RAL.
resource_type View classes, defined resource types, and nodes from
all manifests.
secret_agent Mimics puppet agent.
status View puppet server status.
Available applications, soon to be ported to Faces:
agent The puppet agent daemon
apply Apply Puppet manifests locally
cert Manage certificates and requests
describe Display help about resource types
device Manage remote network devices
doc Generate Puppet documentation and references
filebucket Store and retrieve files in a filebucket
inspect Send an inspection report
kick Remotely control puppet agent
master The puppet master daemon
queue Queuing daemon for asynchronous storeconfigs
See 'puppet help <subcommand> <action>' for help on a specific subcommand
action.
See 'puppet help <subcommand>' for help on a specific subcommand.
Puppet v2.7.14
New Version:
Usage: puppet <subcommand> [options] <action> [options]
Available subcommands:
agent The puppet agent daemon
apply Apply Puppet manifests locally
ca Local Puppet Certificate Authority management.
catalog Compile, save, view, and convert catalogs.
cert Manage certificates and requests
certificate Provide access to the CA for certificate management.
certificate_request Manage certificate requests.
certificate_revocation_list Manage the list of revoked certificates.
config Interact with Puppet's configuration options.
describe Display help about resource types
device Manage remote network devices
doc Generate Puppet documentation and references
facts Retrieve and store facts.
file Retrieve and store files in a filebucket
filebucket Store and retrieve files in a filebucket
help Display Puppet help.
inspect Send an inspection report
instrumentation_data Manage instrumentation listener accumulated data.
instrumentation_listener Manage instrumentation listeners.
instrumentation_probe Manage instrumentation probes.
key Create, save, and remove certificate keys.
kick Remotely control puppet agent
man Display Puppet manual pages.
master The puppet master daemon
module Creates, installs and searches for modules on the
Puppet Forge.
node View and manage node definitions.
parser Interact directly with the parser.
plugin Interact with the Puppet plugin system.
queue Queuing daemon for asynchronous storeconfigs
report Create, display, and submit reports.
resource The resource abstraction layer shell
resource_type View classes, defined resource types, and nodes from
all manifests.
secret_agent Mimics puppet agent.
status View puppet server status.
See 'puppet help <subcommand> <action>' for help on a specific subcommand
action.
See 'puppet help <subcommand>' for help on a specific subcommand.
Puppet v2.7.14
----------------------------------------
Bug #14200: puppet 'help' docs show invalid description of 'resource'
https://projects.puppetlabs.com/issues/14200#change-61498
Author: Chris Price
Status: Accepted
Priority: Urgent
Assignee: Chris Price
Category: Faces
Target version: Telly
Affected Puppet version:
Keywords:
Branch:
Current state of the world:
run 'puppet help', and you will get the following description for 'resource':
resource API only: interact directly with resources via the RAL.
This is the help for the resource *Face*. However, when you actually run
'puppet resource' on the command line, you end up running the resource
*Application*. So the help docs are completely incorrect.
This is an artifact of the fact that when generating help we scan the Faces
first, and assume that they all must have a corresponding application. Most of
them do, but at least the "resource" one does not. Then, when we scan the
Applications, we throw out any of the ones for which we already found a face by
the same name.
Proposed changes:
1. Change the 'help' face to only scan the applications directory. For each
application, if it inherits from "FaceBase", then we'll go grab the docs from
the Face. If not we'll grab the docs from the application.
2. While I'm in here, I'd like to change the ERB template so that our 'help'
screen doesn't differentiate between faces and apps. Users running this
command are just looking for docs for command line tools. They aren't going to
care about the implementation details of a particular tool, and I don't see any
reason to force that information on them.
Also while I'm in here, I will explore "puppet help resource" and make sure
it's not skipping over the application and going to the face, because that is
not useful for a command-line user.
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
