How to write Bundler plugin documentation could be better

[e28eta]

I found documentation for How to write a Bundler plugin and started following it. Step 1 is to go create a gem, and that guide specifically creates a CLI executable using Thor.

Then, back to the bundler_plugins.html.haml page, under "3. Making Bundler commands" link, it gives instructions for registering the command through bundler, but doesn't show any integration with Thor:

bundler-site/source/v2.3/guides/bundler_plugins.html.haml

Lines 116 to 149 in 17f370f

	%p
	To add a Bundler command, you need to make a class that registers itself (or another class) as a command. For example, to add support for a <code>bundler my_command</code> command, you might create a class like so:
	:code
	# lang: ruby
	class MyCommand < Bundler::Plugin::API
	# Register this class as a handler for the `my_command` command
	command "my_command"
	# The exec method will be called with the `command` and the `args`.
	# This is where you should handle all logic and functionality
	def exec(command, args)
	if args.empty?
	# Using BundlerError in plugins is recommended. See below.
	raise BundlerError, 'My plugin requires arguments'
	end
	puts "You called " + command + " with args: " + args.inspect
	end
	end
	or
	:code
	# lang: ruby
	module MyCommand
	# Register this class as a handler for the `my_command` command
	Bundler::Plugin::API.command('my_command', self)
	# The exec method will be called with the `command_name` and the `args`.
	# This is where you should handle all logic and functionality
	def exec(command_name, args)
	puts "You called " + command_name + " with args: " + args.inspect
	end
	end
	%p

The page recommends looking at rubysec/bundler-audit, which afaict does not register a Bundler::Plugin::API.command at all (just relies on the Thor executable being on the path)

As a first time gem author, and first time bundler plugin author, I felt very lost. Questions:

1. Can/ should the 2nd form (Bundler::Plugin::API.command('my_command', self)) be used from within the class with the Thor task? I churned on this for a while, before just creating a new class specific to Bundler. It was complaining about a private exec method (maybe the Kernel version? maybe something internal to Thor?). Might have been my error on something else, but seems like a footgun that is worth warning about.
2. Should Bundler plugins that use Thor for commands even include the command registration? Should I be off making a PR against rubysec/bundler-audit? Or is it a nuanced answer? It looks like doing the registration affects the output of bundle plugin list, but idk about anything else.
3. Should this documentation be updated to show how to link the bundler plugin command and a related Thor task? I used this as my implementation, which afaict works, but maybe there's something different that should be recommended:

      def exec(command_name, args)
        CLI.start(args) # CLI is the name of my Thor task, same as the guide for creating a gem
      end

4. Would documentation updates be made to all versions of bundler_plugins.html.haml? Or do changes like this only get made to the most recent versions?
5. Instructions on Running your plugin locally did not work for me. My plugin has dependencies on other gems, and using --git or --local-git failed because the dependencies couldn't be resolved (or so I believe based on the error message). I had okay luck installing my in-progress gem with bundle exec rake install and then I think bundler plugin install <name> was using the local version instead of what I'd already published on rubygems.org.

I'm interested in improving the documentation, but I don't want to introduce errors, or spend time on something unwanted.

[deivid-rodriguez]

@e28eta Plugins have always been somehow experimental and a work in progress although they're gradually getting better. Regarding 1, 2 and 3, I'm not fully sure, perhaps you can check https://github.com/rubygems/bundler-graph which is meant to be a "reference plugin". If it seems good, we can maybe start pointing there instead of bundle-audit, since bundle-audit does not really use the plugin API as far as I understand.

Regarding 4, I think as long as they are things expected to work on all versions, we should update all versions. If it's documentation of some feature that landed at a specific version, we should only change that version and the ones after.

Regarding 5, I think we fixed some stuff related to that recently. Did you use the latest bundler? If yes, feel free to report an issue.