Here is an example cribbed from the documentation:

schema_version => 1.1,
object_classes => [ 'MyPlugin::Foo', 'MyPlugin::Bar' ],
upgrade_functions => {
    'my_plugin_fix_field_a' => {
        version_limit => 1.1,   # runs for schema_version < 1.1
        code => \&plugin_field_a_fixer
    }
}

Now, while I will readily admit this was very much a faulty assumption on my part, I thought that the keys of that upgrade_functions hash only needed to be unique within the plugin itself.

I was wrong. Very wrong.

The keys of that hash need to be unique within the entire MT installation. That means they cannot be the same as any of the core upgrade functions or any upgrade functions that other plugins might define. It look me about half an hour to track that one down.

Looking back on it now, it makes sense. Template tags, junk filters, text filters, and so forth all need to be unique within the system as well, so it being the same for upgrade functions really is not that surprising when you think about it.

So, I am publicly introducing the first of my plugin development best practices: Always prepend the name of the plugin to any key in the upgrade_functions hash argument.

Yes, this is pretty much what plugin authors do already with template tags (e.g. MTPluginNameTag), but it can't hurt to have this spelled out explicitly for upgrade_functions as well.

--- mason_handler.fcgi.orig     2006-09-30 16:45:18.000000000 -0400
+++ mason_handler.fcgi  2006-09-01 18:05:16.000000000 -0400
@@ -65,6 +65,16 @@
     $ENV{'ENV'}    = '' if defined $ENV{'ENV'};
     $ENV{'IFS'}    = '' if defined $ENV{'IFS'};

+    my $uri = $ENV{REQUEST_URI};
+    if ($uri =~ /\?/) {
+      $uri =~ /^(.*?)\?(.*)/;
+      $ENV{PATH_INFO} = $1;
+      $ENV{QUERY_STRING} = $2;
+    } else {
+      $ENV{PATH_INFO} = $uri;
+      $ENV{QUERY_STRING} = "";
+    }
+
     Module::Refresh->refresh if $RT::DevelMode;
     RT::ConnectToDatabase();

And the portion of my lighttpd configuration file handling Request Tracker:

  server.document-root = "/usr/local/share/html"
  fastcgi.map-extensions        = ( ".css" => ".html", ".js" => ".html", "/" => ".html" )
  index-file.names              = ( "index.html" )
  url.access-deny               = ( ".mhtml" )
  fastcgi.server                = ( ".html" =>
                                        ((
                                                "socket"        => "/tmp/rt-fcgi.socket",
                                                "bin-path"      => "/usr/local/bin/mason_handler.fcgi",
                                                "check-local"   => "disable",
                                                "min-procs"     => 2,
                                                "max-procs"     => 2
                                        ))
                                )