search

rubygems / bundler-site

The Bundler documentation website
https://bundler.io
110 stars 206 forks source link

How to write Bundler plugin documentation could be better #602

Open e28eta opened 2 years ago

e28eta commented 2 years ago

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:

https://github.com/rubygems/bundler-site/blob/17f370fe8ce3493cd1b43387f5969cc6728a092f/source/v2.3/guides/bundler_plugins.html.haml#L116-L149

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 commented 2 years ago

@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.