How to Publish A Rails Plugin
OK, I've got two plugins ready to go in support of my RailsConf 2006 Talk. I've been looking for some information describing the right way to actually publish the plugin so that people can find it with the usual install command.
ruby script/plugin install mysql_bigint
So, I didn't find anything that explained it, but I've poked around a bit and I think I've figured it out. I'm going to document the process that I use here; hopefully that will help others in the future.
Preparing your plugin
Before you publish your plugin you need to be sure that it is ready to publish. Like anything that you put out for public consumption, people will make judgments about you based on what they see there -- so put your best foot forward.
Nice Clean Code. Make sure that your code is clean. It should be appropriately commented, reasonable filenames, etc. Lots of people look at plugin code for ideas on their own plugins or to look for problems or potential improvements. Make this as easy as possible.
Tests Execute. Make sure that your tests execute correctly, preferable on a clean install of Rails. Nothing will turn people off to a plugin faster than tests that don't execute.
README In Place. Use RDoc formatting for your README file and make sure that it adequately documents your plugin. At a minimum it should include the following.
- Installation instructions: including direct from your repository and by plugin name.
- Usage instructions: detailed documentation on how to use the plugin.
- Feedback instruction: how can users get in touch with you to report bugs, submit patches, or just comment.
LICENSE File In Place. Include a copy of the license for your plugin. Most Rails things use the MIT license, but you can use whatever you want.
Create a META.yml file to assist the rails scripts, repositories, and other tools in working with your plugin. This is relatively new, but will be important in the future.
Enable public access to your subversion repository. You need to have public read access established to your subversion repository. I use the repository that is available as part of my Dream Host hosting package. RubyForge and Source Forge are other options for repository hosting. Note that you probably don't want to use the common trunk, tags and branches directories in you repository. This is because the command "script/plugin install http://svn.plug.net/coolplugin/trunk" will install a plugin called trunk rather than coolplugin. If you plan to create more than one plugin, create a plugins directory instead of trunk. Then you can place all of your plugins under there which will make things easier in the next step.
Registering the Plugin
This is the final step to releasing your plugin, registering it so that people can find it.
Start by going to http://wiki.rubyonrails.org/rails/pages/Plugins and editing the page, to add your plugin to the list there. Follow the guidelines established by plugins in the existing list. If you have existing documentation on the web, perhaps generated by using RDoc on your README file, you can use the homepage: section to reference that. The important piece is to set the svn: line to point to your repository so that people know where to go to get your plugin.
The script/plugin discover command scrapes this page to get the list of known repositories. If you used /plugins/ instead of /trunk/ in your repository your repository will be picked up. This will allow people to add your repository to their list of sources and add your plugin by name, like this:
script/plugin install cool_plugin
While the Rails wiki seems to be the most important place to register your plugin, you should also register your plugin at Agile Web Development. They have a growing database of plugins that is searchable and easy to use.
Conclusion
That's it. I hope that this is helpful to everybody. If you have suggestions or improvements to this process comment below!
Steve
