The new Bugzilla::Extension system

[Max Kanat-Alexander]

	I spent the last several days re-writing Bugzilla's extensions system.
The old system suffered from a few problems, many of which I encountered
personally while writing several large extensions:

	* Template hooks went in a strange location that was partially
inexplicable from looking at the code. (Did they go in template/en/hook,
or template/en/default/hook, or template/en/extension, or what?)

	* Code was in individual .pl files that had to be compiled every time
they were run, and couldn't really have subroutines in them (because
Bugzilla would complain you were redefining the subroutine if the hook
was called more than once in the same request).

	There were other things that were strange about them, but those were
the two big points.

	The new system is pretty neat. It's mostly documented in the POD of the
new Bugzilla::Extension module:

	<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Extension.html>

	Here are some of the highlights:

	* Extensions are a directory which contain templates, libraries, and
two special files: Config.pm and Extension.pm. Config.pm contains
information about the extension's requirements. Extension.pm contains
all the code hooks the extension implements, as subroutines.

	* Extensions can also be all in one file, so you could just have
extensions/Foo.pm for an extension named "Foo" that does nothing but add
code hooks.

	* The Extension module is named like Bugzilla::Extension::Foo, where
"Foo" is the "name" of the extension.

	* An extension loads its libraries like Bugzilla::Extension::Foo::Bar.
The extensions system magically maps that to extensions/Foo/lib/Bar.pm,
with no extra effort required by the extension developer. Once the
Bugzilla::Extension::Foo package is loaded, *any* part of Bugzilla can
load Bugzilla::Extension::Foo::Bar directly, if it wants to, just like
"use Bugzilla::Extension::Foo::Bar;". This means, also, that these
libraries could be installed globally in Perl (as
Bugzilla/Extension/Foo/Bar.pm in /usr/lib/perl5/) and still be loaded
properly.

	Note that the old magic @INC behavior of extensions is gone--they
*must* name their packages like Bugzilla::Extension::Foo::Bar. (This is
much better than the strange mix of Foo::Bar and
extensions::foo::lib::Bar that we had before.)

	* Template hooks now live in template/en/default/hook, both in an
extensions directory (extensions/Foo/template/en/default/hook), and in
the base Bugzilla template directory. Templates in extensions (including
hooks) are now precompiled by checksetup.pl. Additionally, template
hooks are cached by Bugzilla the first time they're run, so running them
over and over should just just as fast as (or faster than) processing a
normal template.

	* For new extension authors, there is a script called
extensions/create.pl. You just give it a name of a new extension, as a
single argument, and it creates a whole default layout for an extension
in the extensions/<Name>/ directory.

	* There is support for loading extensions that are not installed in the
extensions/ directory at all, but are installed globally in Perl
instead. This means that extensions could be packaged and distributed
via CPAN, and various code has already been written to make this
possible in Bugzilla itself (though no code has yet been written to make
it easy to make an extension into a CPAN package--this is something that
could still be done).

	* Under mod_perl, extension code will be compiled exactly once, when
the web server starts up. This should make extensions lightning-fast
under mod_perl. (It does mean that to add new extensions, a server
restart is required, though.)

	* To help people who have already written extensions, there is a file,
contrib/extension-convert.pl, which will do a lot of the work of
converting your extension from the pre-3.6 format to the 3.6 format.

	I think extensions should generally be a lot better now, and should
only be getting even better in the future. :-) Please let me know if you
encounter any problems with the new system, or have any suggestions
about it! I'd love to hear from extension authors about their thoughts
on it, particularly if it's after working with it.

	-Max
-- 
http://www.everythingsolved.com/
Competent, Friendly Bugzilla and Perl Services. Everything Else, too.