Once you’ve developed your plugin, tested it, and documented it, the only thing left to do is to share it with the rest of the Rails community. This section describes how to make your code available to the world.
The first thing to consider once you feel you are ready to share your hard work with the rest of the world is quite simple: Is what you have written appropriate for sharing? Here is a quick checklist of things to consider, all of which indicate that your plugin isn’t suited for use by other people.
Do you have the right to release it? If you developed your plugin as part of some commercial endeavor (e.g., at work or on behalf of a client), you may not be legally allowed to make this code available to the rest of the world.
Does it include proprietary business logic?
Does it solve a problem that no one else is likely to encounter, for example, integrating with a custom-made database that nobody else could possibly have?
If you’re still confident that your plugin is going to help the community at large, here’s how to help other developers find and download your plugin.
Licensing
Before you release any code to a general audience, it is also important that you spend some time thinking about what license you release your source code under. The license you assign your plugin will affect the allowed uses of that code in other people’s projects.
For instance, the General Public License (GPL) allows use of your source code by end-users, as long as any derived works are also released under the GPL. Essentially this means that to include a GPL component in your application, your whole application must become GPL-licensed if your application can be considered as derived in some way from the plugin.
In contrast, the MIT license places no such restrictions on reuse, and as such MIT-licensed software (Rails itself, for example) can be included in proprietary projects without difficulty.
There are many different open source software licenses, so it’s well worth spending some time investigating them and selecting whichever feels most comfortable to you. The Open Source Initiative (OSI) maintains a comprehensive list of approved licenses at http://www.opensource.org/licenses/.
In order for other people to download your files, they must be accessible on the Internet. Typically this means that you must either have your own server connected to the Internet with a static IP address or, more likely, an account with a Web hosting provider.
Caution: Hosting and script/plugin
As of the current version of Rails (1.1.4), the script/plugin install command will only work with Subversion repositories, made available either through its native protocols (svn://-style URLs), or via a Web server such as Apache using mod_svn (http://-style URLs).
Many popular Web-hosting companies supply Subversion hosting as part of their package. These include (but are certainly not limited to) TextDrive, PLANET ARGON, DreamHost, and the RailsMachine hosting services (see Table 9.1 for the URLs for each of these). Each of these hosting companies will provide you with publicly accessible Subversion repositories from which you can share your code with the world.
If you don’t have access to a host with Subversion, a number of free Subversion hosts are available. Creating a project on RubyForge will give you access to a repository, along with a very helpful mailing list and issue tracking and collaboration tools without any charge. Alternatively, the OpenSVN project will give you a simple repository, along with an installation of Trac5 for issue tracking.
The many actions required to create a Subversion repository and making it available to the Internet are particular to each hosting provider. Please consult your hosting support for more information about how to set a public repository up.
If for some reason you choose not to set up a publicly accessible Subversion repository, users will not be able to install your plugin using the script/plugin install command. Instead, it is probably simplest to compress your plugin files into a tar.gz or zip file, and share the URL to this file with others who may be interested in using your plugin. They will then have to extract your plugin into their vendor/plugins directory, from which point it will be available in Rails as normal.
It’s important to remember that a plugin’s install.rb file is only automatically invoked by the script/plugin install command. If you choose to package your plugin as a single redistibutable file, you will need to provide instructions and/or rake tasks for performing any setup your plugin may require.
Once your plugin is available on the Internet, the next step is announcing it to the world. We have come across some aspects of this in Section 2 in the discussion about the script/plugin discover command.
At present, the script/plugin discover command “scrapes” the Plugin page on the official Rails wiki (http://wiki.rubyonrails.com/rails/pages/Plugins) for the location of new plugin repositories. To add your plugin, you must go to the wiki and edit this page, adding some information about the plugin and, most importantly, the URL from which it can be downloaded. It’s a good idea to follow the formatting adopted by the majority of the plugin descriptions on that page. This prevents the page from becoming unreadable.
In order for your plugin repository to be recognized by the script/plugin discover command, it should include the string plugins somewhere in it:
http://www.your-server.com/svn/plugins/my_great_plugin svn://svn.your-server.com/plugins/acts_as_clown
Once you have added the description and all-important repository link, your plugin should be available to anyone running script/plugin discover, and subsequently available by the list and install commands discussed in Section 2.
Adding to Plugin Repositories
While appending your plugin information to the Plugin page on the wiki is the only required step to take before your plugin becomes discoverable, it is likely at some point in the future that a dedicated plugin directory will be established. While no official repository currently exists, two candidates have recently emerged to fulfill this need:
http://www.agilewebdevelopment.com/plugins http://plugins.radrails.org/
The RadRails IDE already uses its own plugins repository to help developers find and install plugins, and future versions of the plugin script will almost certainly use a repository like these rather than parsing a wiki page. For the time being, it’s a good idea to add your plugin to these repositories so that any tools (such as RadRails) can take advantage of your code.
The final thing to do is to announce your new plugin on the Rails mailing list. Typically, you should prefix the subject with the abbreviation [ANN], and include the contents of your README file as a description of what the plugin does:
From: [email protected] To: [email protected] Subject: [ANN] acts_as_hasselhoff plugin v1.0 Message: Hi all, I've just written the acts_as_hasselhoff plugin, and I thought I'd share it with the world. It's wearing tight denim jeans and is ready to high-kick your models into action! For real. == Description Makes ActiveRecord models run in unfeasibly slow motion. If the model contains the attribute 'kitt', it will be filled with random witty quips in a style of a British butler using a before_save filter. == Usage To use simply add the line 'acts_as_hasselhoff' to your ActiveRecord model, i.e., class RichardJosephPaul < ActiveRecord::Base acts_as_hasselhoff :character => 'michael knight' # etc
I’m sure you get the idea.
Once your masterpiece is released—to great applause, I have no doubt—you may find yourself on the receiving end of queries, bug reports, and suggestions for improving the plugin. Many of the Web-hosting companies mentioned earlier can either provide or support the use of issue tracking software such as Trac (http://www.edgewall.com/trac/) or Collaboa (http://www.collaboa.org), which can help you organize and manage bugs and improvements.
Issue management software can also provide users with a source of information regarding development progress and a convenient means to supply patches. An example of Collaboa supporting a plugin can be found at the Rails Engines development site (http://dev.rails-engines.org), as shown in Figure 9.1.
