How to Become A Plagger committer

If you have a nice idea of plugin or have a patch to existent Plagger plugins, you can do either of:

  • Email the development mailing list
  • Join the IRC channel #plagger (English) or #plagger-ja (Japanese) on freenode (recommended!)
  • Blog your entry and tag them "plagger" on del.icio.us

If your plugin looks just wonderful, or let me think you can do continous contributions to the Plagger development, I will just give you a subversion commit bit. Do htpasswd -nd youraccount and email me the result. You can use the svn account to login this Trac as well, to create/assign Ticket and edit Wiki content.

Why Committing to SVN?

For now, our plugin API is still premature and will be likely to change a lot until 1.0 release milestone. So I'd recommend you to put the plugins under our control so that users won't be confused. I (miyagawa) will care about the necessary updates to the plugins under svn, if we ever change the plugin APIs.

Once the APIs are finalized, you'll be able to create your plugins and release to CPAN, which is the best repository to distribute Perl modules.

Committers' Best Practices

Don't commit changes to core modules

Because of my release engineering strategy, you just don't commit changes to Plagger core modules directly, even if you have the commit bit to do that. Instead of directly committing, make it a patch and pass the URL for it (or just email the list).

If the patch looks okay, I'll apply them and commit. This is very important to be consistent for the feature roadmap, and possibly to have stricter copyright/licensing management in the future.

See PlaggerCoreModules to see how we define core modules.

Ask before committing the change if possible

Our svn commit bit actually allows you to commit any change you'd like to whenever you want. But please don't.

  • When you create and commit a new plugin, ask for the review on the IRC channel.
  • When you enhance existent plugins, ask for the review first.
  • When you fix obvious bug in the existent plugins (other than PlaggerCoreModules), commit them directly. Opening a ticket on Trac before the commit is encouraged.
  • When you create *.pl or *.yaml meta-plugins (assets) for existent plugins (like EntryFullText?, TruePermalink? and FindEnclosures?), commit them directly.

If you have an ownership for a certain branch, you have the leadership to drive the development and can commit new files directly. See PlaggerBranches for details.

Your code is owned by all once you commit your plugin

Once you commit your plugin to Plagger's svn repository, your code is owned by all Plagger AUTHORS. Of course you have the copyright to the code you wrote, but other committers, especially I, can update your code anytime I would like to. Modifying the plugins would happen occasionally 1) when we update plugin APIs 2) when some features in the plugin can be done using another plugin.

If you're not comfortable your code being edited by someone else, please don't commit them and hold your code under your control. In that case you have to update your plugin by yourself whenever we change the APIs, etc.

License Your Code as Perl

As of this writing, Plagger code is licensed under the same terms as Perl itself. Since I have followling lines in Plagger.pm,

Except where otherwise noted, Plagger is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

plugin codes are thought to be Perl licensed as well, if you don't claim another license in the plugin files.

So, don't steal code from GPLed libraries, for example. That makes your plugin under GPL license. We only accept plugins that are licensed under Perl (Artistic/GPL), MIT or BSD licenses, so that I could avoid the license conflict woes.

Make Your Plugin Simple

Make your plugin as simple as possible. Less code is better, less config is better. Actually, the best interface for the usage of Plagger plugin would be just

- module: Something::Blahblah

and no config: at all. Even if there's something that should be configurable, you have to consider providing the sane defaults, so that 80% of users don't have to bother writing same configuration variables over and over again.

Also, don't do multiple things in a single plugin. Plagger is created based on the very famous Unix philosophy Write programs that do one thing and do it well. Write plugins that do one thing and do it well.

Document Your Plugins

Write documentation of your plugin in the POD section. SYNOPSIS should include the example config directive so that you can use out of the box just by copy-and-paste. If you have some configuration variables which are required/optional, document them. Again, no config is better, since that reduces your work of documentation as well :-)

Write Tests for your Plugins

Since 0.7.x releases, we start to write test suite for core modules, regression bugs and plugins. See trunk/plagger/t/plugins for the existent test suite and start writing unit tests to your plugins. Those tests are enabled only on development and will not be shipped to CPAN users, so that you don't have to deal with modules dependencies.

Write Useful Commit Logs

When I sum up PlaggerChangeLog, I look through the svn log to find what has been changed since the previous release. You have to provide something useful in the svn commit log. Logs like:

bug fix.

are pretty useless and you should avoid. Best commit logs will be something like:

Filter::TruePermalink: Fixed bugs in youtube.yaml to avoid infinite loops.

Note that it contains plugin names and that's very useful.

Use tools/plugin-start.pl to start a new plugin

When you start writing a new plugin, alwayse I<plugin-start.pl> under tools directory, ala:

> tools/plugin-start.pl Foo::Bar

This will create a necessary template for the plugin, dependencies and unit test file. There's no tutorial how to write plugin yet, but there's already hundreds of plugins that you can use as examples.

Write Perl Best Practice compatible code

We test our code to check see if it's conformable to Damian Conway's Perl Best Practices using Perl::Critic and Test::Perl::Critic module. The profile for perlcritic is in trunk/plagger/t/perlcriticrc. You can run

prove -l t/99-perlcritic.t

to see if your code follows what PBP recommends.