Merge branch 'master' of git.freeside.biz:/home/git/freeside

12 files changed, 452 insertions, 312 deletions

diff --git a/rt/docs/UPGRADING-2.0 b/rt/docs/UPGRADING-2.0
index a935552b5..792276f07 100644
--- a/rt/docs/UPGRADING-2.0
+++ b/rt/docs/UPGRADING-2.0
@@ -1,7 +1,7 @@
-UPGRADING FROM 2.x:
+=head1 UPGRADING FROM 2.x
 
-The core RT distribution does not contain the tool to upgrade RT from
-version 2.0; the tool, can be downloaded from CPAN at
+The core RT distribution does not contain the tool to upgrade RT from version
+2.0; the tool, can be downloaded from CPAN at
 http://search.cpan.org/dist/RT-Extension-RT2toRT3/
 
 Further instructions may be found in that distribution's README file.
diff --git a/rt/docs/UPGRADING-3.0 b/rt/docs/UPGRADING-3.0
index 625ca4baf..1bc1b55d3 100644
--- a/rt/docs/UPGRADING-3.0
+++ b/rt/docs/UPGRADING-3.0
@@ -1,18 +1,20 @@
-UPGRADING FROM 3.0.x - Changes:
+=head1 UPGRADING FROM 3.0.0 AND EARLIER
 
-= Installation =
+=head2 Installation
 
 We recommend you move your existing /opt/rt3 tree completely out
 of the way before installing the new version of RT, to make sure
 that you don't inadvertently leave old files hanging around.
 
-= Rights changes =
+
+=head2 Rights changes
 
 Now, if you want RT to automatically create new users upon ticket
 submission, you MUST grant 'Everyone' the right to create tickets.
 Granting this right only to "Unprivileged Users" is now insufficient.
 
-= Web server configuration
+
+=head2 Web server configuration
 
 The configuration for RT's web interface has changed.  Please refer to
 docs/web_deployment.pod for instructions.
diff --git a/rt/docs/UPGRADING-3.2 b/rt/docs/UPGRADING-3.2
index c0b8cebae..4641209e4 100644
--- a/rt/docs/UPGRADING-3.2
+++ b/rt/docs/UPGRADING-3.2
@@ -1,11 +1,10 @@
-UPGRADING FROM 3.2 and earlier - Changes:
+=head1 UPGRADING FROM 3.2.0 AND EARLIER
 
-= Rights changes =
+There have been a number of rights changes.  Now, if you want any user to be
+able to access the Admin tools (a.k.a.  the Configuration tab), you must grant
+that user the "ShowConfigTab" right.  Making the user a privileged user is no
+longer sufficient.
 
-Now, if you want any user to be able to access the Admin tools (a.k.a.
-the Configuration tab), you must grant that user the "ShowConfigTab"
-right.  Making the user a privileged user is no longer sufficient.
-
-"SuperUser" users are no longer automatically added to the list of users
-who can own tickets in a queue. You now need to explicitly give them the
+"SuperUser" users are no longer automatically added to the list of users who
+can own tickets in a queue. You now need to explicitly give them the
 "OwnTicket" right.
diff --git a/rt/docs/UPGRADING-3.4 b/rt/docs/UPGRADING-3.4
index 4dca0451f..20435829d 100644
--- a/rt/docs/UPGRADING-3.4
+++ b/rt/docs/UPGRADING-3.4
@@ -1,12 +1,18 @@
-UPGRADING FROM 3.3.14 and earlier - Changes:
+=head1 UPGRADING FROM 3.3.14 AND EARLIER
 
 The "ModifyObjectCustomFieldValues" right name was too long. It has been
 changed to "ModifyCustomField"
 
 
-UPGRADING FROM 3.3.11 and earlier - Changes:
+=head1 UPGRADING FROM 3.3.11 AND EARLIER
 
-Custom Fields now have an additional right, "ModifyCustomField".  This
-right governs whether a user can modify an object's custom field values
-for a particular custom field. This includes adding, deleting and
-changing values.
+Custom Fields now have an additional right, "ModifyCustomField".  This right
+governs whether a user can modify an object's custom field values for a
+particular custom field. This includes adding, deleting and changing values.
+
+=head1 UPGRADING FROM 3.3.2 AND EARLIER
+
+Viewing custom fields now requires the "SeeCustomField" right either globally
+or on a per-queue basis.  Global CFs are no longer visible to everyone and
+SeeQueue is no longer sufficient to view queue-level CFs.  You must grant the
+"SeeCustomField" right manually after upgrade.
diff --git a/rt/docs/UPGRADING-3.6 b/rt/docs/UPGRADING-3.6
index 3c27709cb..da656c9e5 100644
--- a/rt/docs/UPGRADING-3.6
+++ b/rt/docs/UPGRADING-3.6
@@ -1,29 +1,27 @@
-UPGRADING FROM 3.6.X and earlier - Changes:
+=head1 UPGRADING FROM 3.6.0 AND EARLIER
 
-As there are a large number of code changes, it is highly recommended
-that you install RT into a fresh directory, and then reinstall your
-customizations.
+As there are a large number of code changes, it is highly recommended that you
+install RT into a fresh directory, and then reinstall your customizations.
 
-The database schema has changed significantly for mysql 4.1 and above;
-please read UPGRADING.mysql for more details.
+The database schema has changed significantly for mysql 4.1 and above; please
+read UPGRADING.mysql for more details.
 
-The configuration format has been made stricter. All options MUST be set
-using the Set function; the historical "@XXX = (...) unless @XXX;" is no
-longer allowed.
+The configuration format has been made stricter. All options MUST be set using
+the Set function; the historical "@XXX = (...) unless @XXX;" is no longer
+allowed.
 
 The RTx::Shredder extension has been integrated into core, and several
 features have been added, so you MUST uninstall it before upgrading.
 
-A new interface for making links in text clickable, and doing other
-arbitrary text replacements, has been integrated into RT.  You can read
-more in `perldoc docs/extending/clickable_links.pod`.
+A new interface for making links in text clickable, and doing other arbitrary
+text replacements, has been integrated into RT.  You can read more in `perldoc
+docs/extending/clickable_links.pod`.
 
-A new feature has been added that allows users to forward
-messages. There is a new option in the config ($ForwardFromUser), new
-rights, and a new template.
+A new feature has been added that allows users to forward messages. There is a
+new option in the config ($ForwardFromUser), new rights, and a new template.
 
-New global templates have been added with "Error: " prefixed to the name
-to make it possible to configure error messages sent to users.
+New global templates have been added with "Error: " prefixed to the name to
+make it possible to configure error messages sent to users.
 
 You can read about the new GnuPG integration in `perldoc
 lib/RT/Crypt/GnuPG.pm`.
@@ -31,19 +29,19 @@ lib/RT/Crypt/GnuPG.pm`.
 New scrip conditions 'On Close' and 'On Reopen' have been added.
 
 
-UPGRADING FROM 3.5.7 and earlier - Changes:
+=head1 UPGRADING FROM 3.5.7 AND EARLIER
 
 Scrips are now prepared and committed in order alphanumerically by
-description.  This means that you can prepend a number (00, 07, 15, 24)
-to the beginning of each scrip's description, and they will run in that
-order.  Depending on your database, the old ordering may have been by
-scrip id number -- if that is the case, simply prepend the scrip id
-number to the beginning of its description.
+description.  This means that you can prepend a number (00, 07, 15, 24) to the
+beginning of each scrip's description, and they will run in that order.
+Depending on your database, the old ordering may have been by scrip id number
+-- if that is the case, simply prepend the scrip id number to the beginning of
+its description.
 
 
-UPGRADING FROM 3.5.1 and earlier - Changes:
+=head1 UPGRADING FROM 3.5.1 AND EARLIER
 
 The default for $RedistributeAutoGeneratedMessages has changed to
 'privileged', to make out-of-the-box installations more resistant to
-mail loops. If you rely on the old default of redistributing to all
-watchers, you'll need to set it explicitly now.
+mail loops. If you rely on the old default of redistributing to all watchers,
+you'll need to set it explicitly now.
diff --git a/rt/docs/UPGRADING-3.8 b/rt/docs/UPGRADING-3.8
index cb53030e4..cfe01dfbf 100644
--- a/rt/docs/UPGRADING-3.8
+++ b/rt/docs/UPGRADING-3.8
@@ -1,110 +1,111 @@
-UPGRADING FROM 3.8.8 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.8 AND EARLIER
 
-Previous versions of RT used a password hashing scheme which was too
-easy to reverse, which could allow attackers with read access to the RT
-database to possibly compromise users' passwords.  Even if RT does no
-password authentication itself, it may still store these weak password
-hashes -- using ExternalAuth does not guarantee that you are not
-vulnerable!  To upgrade stored passwords to a stronger hash, run:
+Previous versions of RT used a password hashing scheme which was too easy to
+reverse, which could allow attackers with read access to the RT database to
+possibly compromise users' passwords.  Even if RT does no password
+authentication itself, it may still store these weak password hashes -- using
+ExternalAuth does not guarantee that you are not vulnerable!  To upgrade
+stored passwords to a stronger hash, run:
 
     perl etc/upgrade/vulnerable-passwords
 
-We have also proved that it's possible to delete a notable set of
-records from Transactions table without losing functionality. To delete
-these records, run the following script:
+We have also proved that it's possible to delete a notable set of records from
+Transactions table without losing functionality. To delete these records, run
+the following script:
 
     perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_transactions_table.pl
 
-If you chose not to run the shrink_cgm_table.pl script when you upgraded
-to 3.8, you should read more about it below and run it at this point.
+If you chose not to run the shrink_cgm_table.pl script when you upgraded to
+3.8, you should read more about it below and run it at this point.
 
-The default for $MessageBoxWrap is now SOFT and $MessageBoxWidth is now
-unset by default.  This means the message box will expand to fill all
-the available width.  $MessageBoxWrap is also overridable by the user
-now.  These changes accommodate the new default two column layout for
-ticket create and update pages.  You may turn this layout off by setting
-$UseSideBySideLayout to 0.  To retain the original behavior, set
-$MessageBoxWrap to HARD and $MessageBoxWidth to 72.
+The default for $MessageBoxWrap is now SOFT and $MessageBoxWidth is now unset
+by default.  This means the message box will expand to fill all the available
+width.  $MessageBoxWrap is also overridable by the user now.  These changes
+accommodate the new default two column layout for ticket create and update
+pages.  You may turn this layout off by setting $UseSideBySideLayout to 0.  To
+retain the original behavior, set $MessageBoxWrap to HARD and $MessageBoxWidth
+to 72.
 
 
-UPGRADING FROM 3.8.7 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.7 AND EARLIER
 
-RT's ChartFont option has been changed from a string to a hash which
-lets you specify per-language fonts. RT now comes with a better default
-font for charts, too.  You should either update your 'ChartFont' option
-to match the new format, or consider trying the new default.
+RT's ChartFont option has been changed from a string to a hash which lets you
+specify per-language fonts. RT now comes with a better default font for
+charts, too.  You should either update your 'ChartFont' option to match the
+new format, or consider trying the new default.
 
-RT now gives you more precise control over the order in which custom
-fields are displayed.  This change requires some small changes to your
-currently saved custom field orders.  RT will automatically clean up
-your existing custom fields when you run the standard database upgrade
-steps.  After that cleanup, you should make sure that custom fields are
-ordered in a way that you and your users find pleasing.
+RT now gives you more precise control over the order in which custom fields
+are displayed.  This change requires some small changes to your currently
+saved custom field orders.  RT will automatically clean up your existing
+custom fields when you run the standard database upgrade steps.  After that
+cleanup, you should make sure that custom fields are ordered in a way that you
+and your users find pleasing.
 
 
-UPGRADING FROM 3.8.6 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.6 AND EARLIER
 
-For MySQL and Oracle users:
-If you upgraded from a version of RT earlier than 3.7.81, you should
-already have a CachedGroupMembers3 index on your CachedGroupMembers
-table.  If you did a clean install of RT somewhere in the 3.8 release
-series, you most likely don't have this index.  You can add it manually
-with:
+For MySQL and Oracle users: if you upgraded from a version of RT earlier than
+3.7.81, you should already have a CachedGroupMembers3 index on your
+CachedGroupMembers table.  If you did a clean install of RT somewhere in the
+3.8 release series, you most likely don't have this index.  You can add it
+manually with:
 
   CREATE INDEX CachedGroupMembers3 on CachedGroupMembers (MemberId, ImmediateParentId);
 
 
-UPGRADING FROM 3.8.5 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.5 AND EARLIER
 
 You can now forward an entire Ticket history (in addition to specific
-transactions) but this requires a new Template called "Forward Ticket".
-This template will be added as part of the standard database upgrade
-step.
+transactions) but this requires a new Template called "Forward Ticket".  This
+template will be added as part of the standard database upgrade step.
 
-Custom fields with categories can optionally be split out into
-hierarchical custom fields.  If you wish to convert your old
-category-based custom fields, run:
+Custom fields with categories can optionally be split out into hierarchical
+custom fields.  If you wish to convert your old category-based custom fields,
+run:
 
     perl etc/upgrade/split-out-cf-categories
 
-It will prompt you for each custom field with categories that it finds,
-and the name of the custom field to create to store the categories.
+It will prompt you for each custom field with categories that it finds, and
+the name of the custom field to create to store the categories.
 
-If you were using the LocalizedDateTime RT::Date formatter from custom
-code, and passing a DateFormat or TimeFormat argument, you need to
-switch from the strftime methods to the cldr methods; that is,
+If you were using the LocalizedDateTime RT::Date formatter from custom code,
+and passing a DateFormat or TimeFormat argument, you need to switch from the
+strftime methods to the cldr methods; that is,
 'full_date_format' becomes 'date_format_full'.
 
 You may also have done this from your RT_SiteConfig.pm, using:
+
     Set($DateTimeFormat, {
         Format => 'LocalizedDateTime',
         DateFormat => 'medium_date_format',
     );
+
 Which would need to be changed to:
+
     Set($DateTimeFormat, {
         Format => 'LocalizedDateTime',
         DateFormat => 'date_format_medium',
     );
 
 
-UPGRADING FROM 3.8.3 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.3 AND EARLIER
 
 Arguments to the NotifyGroup Scrip Action will be updated as part of the
 standard database upgrade process.
 
 
-UPGRADING FROM 3.8.2 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.2 AND EARLIER
 
 A new scrip condition, 'On Reject', has been added.
 
 
-UPGRADING FROM 3.8.1 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.1 AND EARLIER
 
-When using Oracle, $DatabaseName is now used as SID, so RT can connect
-without environment variables or tnsnames.ora file. Because of this
-change, your RT instance may loose its ability to connect to your DB; to
-resolve this, you will need to update RT's configuration and restart
-your web server.  Example configuration:
+When using Oracle, $DatabaseName is now used as SID, so RT can connect without
+environment variables or tnsnames.ora file. Because of this change, your RT
+instance may loose its ability to connect to your DB; to resolve this, you
+will need to update RT's configuration and restart your web server.  Example
+configuration:
 
     Set($DatabaseType, 'Oracle');
     Set($DatabaseHost, '192.168.0.1');
@@ -121,72 +122,70 @@ If you want a user to be able to access the Approvals tools (a.k.a.  the
 Approvals tab), you must grant that user the "ShowApprovalsTab" right.
 
 
-UPGRADING FROM 3.8.0 and earlier - Changes:
+=head1 UPGRADING FROM 3.8.0 AND EARLIER
 
-The TicketSQL syntax for bookmarked tickets has been changed.
-Specifically, the new phrasing is "id = '__Bookmarked__'", rather than
-the old "__Bookmarks__".  The old form will remain, for backwards
-compatibility.  The standard database upgrade process will only
-automatically change the global 'Bookmarked Tickets' search
+The TicketSQL syntax for bookmarked tickets has been changed.  Specifically,
+the new phrasing is "id = '__Bookmarked__'", rather than the old
+"__Bookmarks__".  The old form will remain, for backwards compatibility.  The
+standard database upgrade process will only automatically change the
+global 'Bookmarked Tickets' search
 
 
-UPGRADING FROM 3.7.85 and earlier - Changes:
+=head1 UPGRADING FROM 3.7.85 AND EARLIER
 
-We have proved that it is possible to delete a large set of records from
-the CachedGroupMembers table without losing functionality; in fact,
-failing to do so may result in occasional problems where RT miscounts
-users, particularly in the chart functionality.  To delete these records
-run the following script:
+We have proved that it is possible to delete a large set of records from the
+CachedGroupMembers table without losing functionality; in fact, failing to do
+so may result in occasional problems where RT miscounts users, particularly in
+the chart functionality.  To delete these records run the following script:
 
     perl -I /opt/rt4/local/lib -I /opt/rt4/lib etc/upgrade/shrink_cgm_table.pl
 
-After you run this, you will have significantly reduced the number of
-records in your CachedGroupMembers table, and may need to tell your
-database to refresh indexes/statistics.  Please consult your DBA for
-specific instructions for your database.
+After you run this, you will have significantly reduced the number of records
+in your CachedGroupMembers table, and may need to tell your database to
+refresh indexes/statistics.  Please consult your DBA for specific instructions
+for your database.
 
 
-UPGRADING FROM 3.7.81 and earlier - Changes:
+=head1 UPGRADING FROM 3.7.81 AND EARLIER
 
-RT::Extension::BrandedQueues has been integrated into core, and the
-handling of subject tags has changed as a consequence.  You will need to
-modify any of your email templates which use the $rtname variable, in
-order to make them respect the per-queue subject tags. To edit your
-templates, log into RT as your administrative user, then click:
+RT::Extension::BrandedQueues has been integrated into core, and the handling
+of subject tags has changed as a consequence.  You will need to modify any of
+your email templates which use the $rtname variable, in order to make them
+respect the per-queue subject tags. To edit your templates, log into RT as
+your administrative user, then click:
 
     Configuration -> Global -> Templates -> Select -> <Some template name>
 
-The only template which ships with RT which needs updating is the
-"Autoreply" template, which includes this line:
+The only template which ships with RT which needs updating is the "Autoreply"
+template, which includes this line:
 
-    "There is no need to reply to this message right now.  Your ticket
-    has been assigned an ID of [{$rtname} #{$Ticket->id()}]."
+    "There is no need to reply to this message right now.  Your ticket has
+    been assigned an ID of [{$rtname} #{$Ticket->id()}]."
 
 Change this line to read:
 
-    "There is no need to reply to this message right now.  Your ticket
-    has been assigned an ID of { $Ticket->SubjectTag }."
+    "There is no need to reply to this message right now.  Your ticket has
+    been assigned an ID of { $Ticket->SubjectTag }."
 
-If you were previously using RT::Extension::BrandedQueues, you MUST
-uninstall it before upgrading. In addition, you must run the
+If you were previously using RT::Extension::BrandedQueues, you MUST uninstall
+it before upgrading. In addition, you must run the
 'etc/upgrade/3.8-branded-queues-extension' perl script.  This will
 convert the extension's configuration into the new format.  Finally, in
 templates where you were using the Tag method ($Ticket->QueueObj->Tag),
 you will need to replace it with $Ticket->SubjectTag
 
-RT::Action::LinearEscalate extension has been integrated into core,
-so you MUST uninstall it before upgrading.
+RT::Action::LinearEscalate extension has been integrated into core, so you
+MUST uninstall it before upgrading.
 
-RT::Extension::iCal has been integrated into core, so you MUST uninstall
-it before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
+RT::Extension::iCal has been integrated into core, so you MUST uninstall it
+before upgrading. In addition, you must run etc/upgrade/3.8-ical-extension
 script to convert old data.
 
 
-UPGRADING FROM 3.7.80 and earlier - Changes:
+=head1 UPGRADING FROM 3.7.80 AND EARLIER
 
-Added indexes to CachedGroupMembers for MySQL and Oracle.
-If you have previously installed RTx-Shredder, you may already
-have these indexes.  You can see the indexes by looking at
-etc/upgrade/3.7.81/schema.*
+Added indexes to CachedGroupMembers for MySQL and Oracle.  If you have
+previously installed RTx-Shredder, you may already have these indexes.  You
+can see the indexes by looking at etc/upgrade/3.7.81/schema.*
 
 These indexes may take a very long time to create.
diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0
index 4b64d2e72..687dfbc61 100644
--- a/rt/docs/UPGRADING-4.0
+++ b/rt/docs/UPGRADING-4.0
@@ -1,87 +1,103 @@
-Common Issues
+=head1 UPGRADING FROM BEFORE 4.0.0
 
-RT now defaults to a database name of rt4 and an installation root of /opt/rt4.
+=head2 Common issues
 
-If you are upgrading, you will likely want to specify that your database
-is still named rt3 (or import a backup of your database as rt4 so that
-you can feel more confident making the upgrade).
+RT now defaults to a database name of rt4 and an installation root of
+/opt/rt4.
 
-You really shouldn't install RT4 into your RT3 source tree (/opt/rt3)
-and instead should be using make install to set up a clean environment.
-This will allow you to evaluate your local modifications and configuration
-changes as you migrate to 4.0.
+If you are upgrading, you will likely want to specify that your database is
+still named rt3 (or import a backup of your database as rt4 so that you can
+feel more confident making the upgrade).
+
+You really shouldn't install RT4 into your RT3 source tree (/opt/rt3) and
+instead should be using make install to set up a clean environment.  This will
+allow you to evaluate your local modifications and configuration changes as
+you migrate to 4.0.
 
 If you choose to force RT to install into /opt/rt3, or another existing RT 3.x
 install location, you will encounter issues because we removed the _Overlay
-files (such as Ticket_Overlay.pm) and relocated other files.  You will
-need to manually remove these files after the upgrade or RT will fail.
-After making a complete backup of your /opt/rt3 install, you might use a
-command like the following to remove the _Overlay files:
+files (such as Ticket_Overlay.pm) and relocated other files.  You will need to
+manually remove these files after the upgrade or RT will fail.  After making a
+complete backup of your /opt/rt3 install, you might use a command like the
+following to remove the _Overlay files:
 
     find /opt/rt3/lib/ -type f -name '*_Overlay*' -delete
 
 RT has also changed how web deployment works; you will need to review
-docs/web_deployment.pod for current instructions.  The old
+F<docs/web_deployment.pod> for current instructions.  The old
 `fastcgi_server`, `webmux.pl`, and `mason_handler.*` files will not
 work with RT 4.0, and should be removed to reduce confusion.
 
-*******
-RT_SiteConfig.pm
+If you deploy RT with mod_perl, Apache will no longer start with C<SetHandler>
+set to `perl-script`. F<docs/web_deployment.pod> contains the
+new configuration.
+
+
+=head2 RT_SiteConfig.pm
+
+You will need to carefully review your local settings when moving from 3.8 to
+4.0.
 
-You will need to carefully review your local settings when moving from
-3.8 to 4.0.
+If you were adding your own custom statuses in earlier versions of RT, using
+ActiveStatus or InactiveStatus you will need to port these to use the new
+Lifecycles functionality.  You can read more about it in RT_Config.pm.  In
+most cases, you can do this by extending the default active and inactive
+lists.
 
-If you were adding your own custom statuses in earlier versions of RT,
-using ActiveStatus or InactiveStatus you will need to port these to use
-the new Lifecycles functionality.  You can read more about it in
-RT_Config.pm.  In most cases, you can do this by extending the default
-active and inactive lists.
 
-*******
-Upgrading sessions on MySQL
+=head2 Upgrading sessions on MySQL
 
-In 4.0.0rc2, RT began shipping an updated schema for the sesions table
-that specificies a character set as well as making the table InnoDB.  As
-part of the upgrade process, your sessions table will be dropped and
-recreated with the new schema.
+In 4.0.0rc2, RT began shipping an updated schema for the sesions table that
+specificies a character set as well as making the table InnoDB.  As part of
+the upgrade process, your sessions table will be dropped and recreated with
+the new schema.
 
-*******
-UPGRADING FROM RT 3.8.x and RTFM 2.1 or greater
 
-RT4 now includes an Articles functionality, merged from RTFM.
-You should not install and enable the RT::FM plugin separately on RT 4.
-If you have existing data in RTFM, you can use the etc/upgrade/upgrade-articles
-script to upgrade that data.
+=head2 Upgrading from installs with RTFM
 
-When running normal upgrade scripts, RT will warn if it finds existing
-RTFM tables that contain data and point you to the upgrade-articles script.
+RT4 now includes an Articles functionality, merged from RTFM.  You should not
+install and enable the RT::FM plugin separately on RT 4.  If you have existing
+data in RTFM, you can use the etc/upgrade/upgrade-articles script to upgrade
+that data.
 
-This script should be run from your RT tarball.  It will immediately
-begin populating your new RT4 tables with data from RTFM.  If you have
-browsed in the RT4 UI and created new classes and articles, this script
-will fail spectacularly.  Do *not* run this except on a fresh upgrade of
-RT.
+When running normal upgrade scripts, RT will warn if it finds existing RTFM
+tables that contain data and point you to the upgrade-articles script.
+
+This script should be run from your RT tarball.  It will immediately begin
+populating your new RT4 tables with data from RTFM.  If you have browsed in
+the RT4 UI and created new classes and articles, this script will fail
+spectacularly.  Do *not* run this except on a fresh upgrade of RT.
 
 You can run this as
 
   etc/upgrade/upgrade-articles
 
-It will ouput a lot of data about what it is changing.  You should
-review this for errors.
+It will ouput a lot of data about what it is changing.  You should review this
+for errors.
 
-If you are running RTFM 2.0 with a release of RT, there isn't currently an upgrade
-script that can port RTFM's internal CustomField and Transaction data to RT4.
+If you are running RTFM 2.0 with a release of RT, there isn't currently an
+upgrade script that can port RTFM's internal CustomField and Transaction data
+to RT4.
 
 You must also remove RT::FM from your @Plugins line in RT_SiteConfig.pm.
 
-*******
-The deprecated classes RT::Action::Generic, RT::Condition::Generic and RT::Search::Generic
-have been removed, but you shouldn't have been using them anyway. You should have been using
-RT::Action, RT::Condition and RT::Search, respectively.
 
-* The "Rights Delegation" and "Personal Groups" features have been removed.
+=head2 Removals and updates
+
+The deprecated classes RT::Action::Generic, RT::Condition::Generic and
+RT::Search::Generic have been removed, but you shouldn't have been using them
+anyway. You should have been using RT::Action, RT::Condition and RT::Search,
+respectively.
+
+=over
 
-* Replace the following code in templates:
+=item *
+
+The "Rights Delegation" and "Personal Groups" features have been removed.
+
+=item *
+
+Replace the following code in templates:
 
     [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
 
@@ -89,38 +105,45 @@ with
 
     { $Ticket->SubjectTag }
 
-* Unique names are now enforced for user defined groups.  New groups cannot be
-  created with a duplicate name and existing groups cannot be renamed to an
-  in-use name.  The admin interface will warn about existing groups with
-  duplicate names.  Although the groups will still function, some parts of the
-  interface (rights management, subgroup membership) may not work as expected
-  with duplicate names.  Running
+=item *
+
+Unique names are now enforced for user defined groups.  New groups cannot be
+created with a duplicate name and existing groups cannot be renamed to an
+in-use name.  The admin interface will warn about existing groups with
+duplicate names.  Although the groups will still function, some parts of the
+interface (rights management, subgroup membership) may not work as expected
+with duplicate names.  Running
 
     /opt/rt4/sbin/rt-validator --check
 
-  will report duplicate group names, and running it with --resolve will fix
-  duplicates by appending the group id to the name.
+will report duplicate group names, and running it with --resolve will fix
+duplicates by appending the group id to the name.
+
+Nota Bene: As a result of differing indexes in the schema files, Postgres and
+SQLite RT databases have enforced group name uniqueness for many years at the
+database level.
+
+=back
+
 
-  Nota Bene: As a result of differing indexes in the schema files, Postgres and
-  SQLite RT databases have enforced group name uniqueness for many years at the
-  database level.
 
-*******
+=head1 UPGRADING FROM 4.0.5 AND EARLIER
 
-UPGRADING FROM 4.0.5 and earlier - Changes:
+=head2 Schema updates
 
 The fix for an attribute truncation bug on MySQL requires a small ALTER TABLE.
 Be sure you run `make upgrade-database` to apply this change automatically.
 The bug primarily manifested when uploading large logos in the theme editor on
-MySQL.  Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE that
-will be run.
+MySQL.  Refer to etc/upgrade/4.0.6/schema.mysql for the actual ALTER TABLE
+that will be run.
+
+
+=head2 Query Builder
 
-*******
 The web-based query builder now uses Queue limits to restrict the set of
 displayed statuses and owners.  As part of this change, the %cfqueues
-parameter was renamed to %Queues; if you have local modifications to any
-of the following Mason templates, this feature will not function
-correctly:
+parameter was renamed to %Queues; if you have local modifications to any of
+the following Mason templates, this feature will not function correctly:
 
     share/html/Elements/SelectOwner
     share/html/Elements/SelectStatus
@@ -129,3 +152,40 @@ correctly:
     share/html/Search/Elements/BuildFormatString
     share/html/Search/Elements/PickCFs
     share/html/Search/Elements/PickCriteria
+
+=head1 UPGRADING FROM 4.0.8 AND EARLIER
+
+=head2 Data upgrades
+
+Previously, the default lifecycle was stored in Queues.Lifecycle as
+NULL. To simplify code, RT now stores the string 'default' to match the
+name of the Lifecycle.
+
+The 3.9.2 upgrade step removed all enabled Personal Groups, but missed
+any disabled groups. We catch and clean up the disabled Personal groups
+during the 4.0.9 upgrade step.
+
+=head2 Javascript Changes
+
+If you have set a custom @JSFiles in RT_SiteConfig.pm, you will need to
+amend this to include the new jquery.cookie.js file added to
+RT_Config.pm.  If you are using an extension that requires manually
+tweaking @JSFiles, please contact the developer and ask them to use
+RT->AddJavaScript in their extension to avoid these upgrade problems.
+
+If you have @JSFiles set in your RT_SiteConfig.pm but it appears to be
+the same as RT_Config.pm (no local js files added) you can safely remove
+the whole setting from RT_SiteConfig.pm and allow our default to be
+used.
+
+=head1 UPGRADING FROM 4.0.11 AND EARLIER
+
+=head2 Data Upgrades
+
+Previous versions of RT allowed you to create Tickets with a Type of
+'Ticket', 'Approval' or 'Reminder' instead of the correct 'ticket'.
+Existing Types are updated in the database and the RT API now corrects
+these types before insertion.
+
+Site-specific custom types (anything but ticket, reminder or approval)
+are not affected by these changes.
diff --git a/rt/docs/UPGRADING.mysql b/rt/docs/UPGRADING.mysql
index 77a6b389f..a62dee78b 100644
--- a/rt/docs/UPGRADING.mysql
+++ b/rt/docs/UPGRADING.mysql
@@ -1,85 +1,142 @@
-If you did not start by reading the README file, please start there;
-these steps do not list the full upgrading process, merely a part which
-is sometimes necessary.
+If you did not start by reading the README file, please start there; these
+steps do not list the full upgrading process, merely a part which is sometimes
+necessary.
 
 This file applies if either:
 
- 1) You are upgrading RT from a version prior to 3.8.0, on any version
-    of MySQL
-............. OR .............
- 2) You are migrating from MySQL 4.0 to MySQL 4.1 or above
+=over
+
+=item 1.
+
+You are upgrading RT from a version prior to 3.8.0, on any version
+of MySQL
+
+=item 2.
+
+You are migrating from MySQL 4.0 to MySQL 4.1 or above
+
+=back
 
 If neither of the above cases apply, your should upgrade as per the
 instructions in the README.
 
-These changes are necessary because MySQL 4.1 and greater changed some
-aspects of character set handling that may result in RT failures; this
-will manifest as multiple login requests, corrupted binary attachments,
-and corrupted image custom fields, among others.  In order to resolve
-this issue, the upgrade process will need to modify the schema.
+These changes are necessary because MySQL 4.1 and greater changed some aspects
+of character set handling that may result in RT failures; this will manifest
+as multiple login requests, corrupted binary attachments, and corrupted image
+custom fields, among others.  In order to resolve this issue, the upgrade
+process will need to modify the schema.
+
+=over
+
+=item 1.
+
+If you are moving the database and/or upgrading MySQL
+
+=over
+
+=item 1a.
+
+Dump the database; with MySQL 4.1 and greater be sure to pass the mysqldump
+command the --default-character-set=binary option.  This is necessary because
+the data was originally encoded in Latin1.
+
+=item 1b.
+
+Configure the new MySQL to use Latin1 as the default character set everywhere,
+not UTF-8.  This is necessary so the import in the next step assumes the data
+is Latin1.
+
+=item 1c.
+
+Import the dump made in step 1a into the new MySQL server, using the
+--default-character-set=binary option on restore.  This will ensure that the
+data is imported as bytes, which will be interpreted as Latin1 thanks to step
+1b above.
+
+=item 1d.
+
+Test that your RT works as expected on this new database.
+
+=back
+
+=item 2.
+
+Backup RT's database using --default-character-set=binary  Furthermore, test
+that you can restore from this backup.
+
+=item 3.
+
+Follow instructions in the README file to step 6b.
+
+=item 4.
+
+Apply changes described in the README's step 6b, but only up to version
+3.7.87.
+
+=item 5.
+
+Apply the RT 3.8 schema upgrades. Included in RT is the script
+etc/upgrade/upgrade-mysql-schema.pl that will generate the appropriate SQL
+queries:
+
+    perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
+
+If your mysql database is on a remote host, you can run the script like this
+instead:
+
+    perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
+
+=item 6.
+
+Check the sanity of the SQL queries in the queries.sql file yourself, or
+consult with your DBA.
+
+=item 7.
+
+Apply the queries. Note that this step can take a while; it may also require
+additional space on your hard drive comparable with size of your tables.
 
- 1) If you are moving the database and/or upgrading MySQL
-   1a) Dump the database; with MySQL 4.1 and greater be sure to pass
-       the mysqldump command the --default-character-set=binary option.
-       This is necessary because the data was originally encoded in
-       Latin1.
+    mysql -u root -p rt3 < queries.sql
 
-   1b) Configure the new MySQL to use Latin1 as the default character
-       set everywhere, not UTF-8.  This is necessary so the import in
-       the next step assumes the data is Latin1.
+NOTE that 'rt3' is the default name of the RT database, change it in the
+command above if your database is named differently.
 
-   1c) Import the dump made in step 1a into the new MySQL server, using
-       the --default-character-set=binary option on restore.  This will
-       ensure that the data is imported as bytes, which will be
-       interpreted as Latin1 thanks to step 1b above.
+This step should not produce any errors or warnings. If you see any, restore
+your database from the backup you made at step 1, and send a report to the
+rt-users@lists.bestpractical.com mailing list.
 
-   1d) Test that your RT works as expected on this new database.
+=item 8.
 
- 2) Backup RT's database using --default-character-set=binary
-    Furthermore, test that you can restore from this backup.
+Re-run the `make upgrade-database` command from step 6b of the README,
+applying the rest of the upgrades, starting with 3.7.87, and follow the
+README's remaining steps.
 
- 3) Follow instructions in the README file to step 6b.
+=item 9.
 
- 4) Apply changes described in the README's step 6b, but only up to
-    version 3.7.87.
+Test everything. The most important parts you have to test:
 
- 5) Apply the RT 3.8 schema upgrades. Included in RT is the script
-    etc/upgrade/upgrade-mysql-schema.pl that will generate the
-    appropriate SQL queries:
+=over
 
-        perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
+=item *
 
-    If your mysql database is on a remote host, you can run the script
-    like this instead:
+binary attachments, like docs, PDFs, and images
 
-        perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
+=item *
 
- 6) Check the sanity of the SQL queries in the queries.sql file
-    yourself, or consult with your DBA.
+binary custom fields
 
- 7) Apply the queries. Note that this step can take a while; it may also
-    require additional space on your hard drive comparable with size of
-    your tables.
+=item *
 
-        mysql -u root -p rt3 < queries.sql
+everything that may contain characters other than ASCII
 
-    NOTE that 'rt3' is the default name of the RT database, change it in
-    the command above if your database is named differently.
+=back
 
-    This step should not produce any errors or warnings. If you see any,
-    restore your database from the backup you made at step 1, and send a
-    report to the rt-users@lists.bestpractical.com mailing list.
 
- 8) Re-run the `make upgrade-database` command from step 6b of the
-    README, applying the rest of the upgrades, starting with 3.7.87, and
-    follow the README's remaining steps.
+=item 10.
 
- 9) Test everything. The most important parts you have to test:
-     * binary attachments, like docs, PDFs, and images
-     * binary custom fields
-     * everything that may contain characters other than ASCII
+If you were upgrading from MySQL 4.0, you may now, if you wish, reconfigure
+your newer MySQL instance to use UTF-8 as the default character set, as step 7
+above adjusted the character sets on all existing tables to contain UTF-8
+encoded data, rather than Latin1.
 
-10) If you were upgrading from MySQL 4.0, you may now, if you wish,
-    reconfigure your newer MySQL instance to use UTF-8 as the default
-    character set, as step 7 above adjusted the character sets on all
-    existing tables to contain UTF-8 encoded data, rather than Latin1.
+=back
diff --git a/rt/docs/customizing/articles_introduction.pod b/rt/docs/customizing/articles_introduction.pod
index ea49b05de..73b5c334d 100644
--- a/rt/docs/customizing/articles_introduction.pod
+++ b/rt/docs/customizing/articles_introduction.pod
@@ -11,7 +11,7 @@ RT.  They are organized into classes and topics.
 The user interface to Articles is available from the Tools -> Articles
 menu.  Admin functionality can be found under Tools -> Configuration ->
 Articles.  Once configured, articles will become available for searching
-on the Reply/Comment page on tickets.  There are configuration variables
+on the Reply/Comment page on tickets.  There are L</"Configuration Options">
 to make Articles available on ticket creation.
 
 =head2 Basics
@@ -30,20 +30,24 @@ Classes are equivalent to RT's queues.  They can be created by going
 to Tools -> Configuration -> Articles -> Classes -> New Class.  Articles
 are assigned to one Class.  When you create Custom Fields for use with
 Articles, they will be applied Globally or to a Class, like Custom
-Fields are applied to a Queue in RT.  Each class also controls what
-information is included into a reply (such as the Class header and
-footer) and the Article.
+Fields are applied to a Queue in RT.
 
-Classes need to be Applied, just like a Custom Field by using the
-Applied To link.  You can apply them globally or on a queue-by-queue
-basis.
+A common use for Articles is to store frequently
+used replies for requestors, like troubleshooting steps or how to sign
+up for a new account. When you insert Article text, you may or may not
+want to include the Article name and summary, in addition to the content,
+when inserting the Article in a reply. You can control this behavior on
+the Class configuration page.
 
-hotlist.
+Classes need to be Applied, just like a Custom Field, by using the
+Applies To link on the Modify Class page (Tools -> Configuration ->
+Articles -> Classes, select the class to modify).  You can apply
+them globally or on a queue-by-queue basis.
 
 =head3 Topics
 
 You can also use Topics to organize your Articles.  While editing a
-Class, there is a Topic tab for Class specific Topics.  You can create
+Class, there is a Topics tab for Class-specific Topics.  You can create
 global Topics from the Global tab under Tools -> Configuration.
 
 When editing Topics, type the name (and optionally description) of the
@@ -53,9 +57,9 @@ tree of Topics should show up when creating or modifying articles in
 the class. These can be arbitrarily nested.
 
 Global Topics will be available for all Articles, regardless of their
-Class.  Articles can belong to both global and class-specific Topics.
+Class.  Articles can belong to both global and Class-specific Topics.
 
-Articles topics can be set from the 'Modify' screen for the article --
+Article topics can be set from the Modify screen for the article --
 simply select as many topics as you desire from the list at the bottom
 of the screen.
 
@@ -63,18 +67,20 @@ of the screen.
 
 Articles don't have a single "body" section for each
 article. Everything is a custom field (except for name, summary and
-some other basic metadata). So, you need to create some custom
-fields to hold the Article body and other data.  These Custom Fields
-should have "Applies To" be "RTFM Articles".
+some other basic metadata). So to put information on an
+Article, you need to create some custom fields to hold the Article
+body and other data.  When you create these new Custom Fields, set
+the Applies To field to Articles.
 
-Once you've created your custom fields, go into your classes and click
-on "Custom Fields" and add the Custom Fields you want to each class.
+Once you've created your Custom Fields, go into your Classes, click
+on Custom Fields, and add the Custom Fields you want to each Class.
 Alternatively, use the Applies To link from each Custom Field.
 
 =head2 Creating Articles
 
-You can create an article from scratch by going to Tools -> Articles ->
+You can create an Article from scratch by going to Tools -> Articles ->
 New Article and then picking which Class to create the Article under.
+You must have a Class to assign the new Article to.
 The Summary, Description and Custom Fields will all be searchable when
 including an Article and you can control what Custom Fields end up in
 your Ticket from the Class configuration page.
@@ -84,11 +90,11 @@ your Ticket from the Class configuration page.
 You can extract the body of a ticket into an article. Within RT, you
 should now see an "Extract to article" button in the upper right hand
 corner of RT's UI when working with tickets. When you click that
-button, RT will ask you which Class to create your new article in.
-Once you click on a class name, the Ticket's transactions will be
+button, RT will ask you which Class to create your new Article in.
+Once you click on a Class name, the Ticket's transactions will be
 displayed, along with a set of select boxes. For each transaction, you
 can pick which Custom Field that transaction should be extracted to.
-From there on in, it's just regular article creation.
+From there on in, it's just regular Article creation.
 
 =head2 Including an Article
 
@@ -97,14 +103,14 @@ is a UI widget that lets you search for and include Articles in
 your reply.  (They're editable, of course).  
 
 Articles can be included by searching for them, knowing the Id of the
-article, using the Article Hotlist and using the Queue specific
+article, using the Article Hotlist and using the Queue-specific
 dropdown.
 
-=head2 Queue Specific List of Articles 
+=head2 Queue-Specific List of Articles 
 
-You can use Topics to organize a set of Queue specific Articles.
+You can use Topics to organize a set of Queue-specific Articles.
 Simply create a global Topic called 'Queues' and then create Topics
-under Queues named after each of your Queues.  Within each Queue named
+under Queues named after each of your Queues.  Within each Queue-named
 Topic, create some Topics and then assign Articles to those
 sub-topics.  This creates a hierarchy like this:
 
@@ -118,38 +124,44 @@ offered a choice of Topic 1 and Topic 2 along with the searching.
 After choosing Topic 1 or Topic 2, you will be given a list of
 relevant articles to choose.
 
-Alternately, you can now implement this by applying a single class to
-your queue and using the L<Article Hotlist> feature described below.
+Alternately, you can now implement this by applying a single Class to
+your Queue and using the L</"Article Hotlist"> feature described below.
 
 =head2 Article Hotlist
 
-If you enable "All articles in this class are on dropdown on ticket
-reply page" option, there will be a dropdown on the Create or Update
-page which allows users to quickly include Articles.
+The Modify Class page has a checkbox labelled "All Articles in this
+class should be listed in a dropdown of the ticket reply page".
+If you select this for a Class, a dropdown will be available on the
+Ticket Create or Update page which allows users to quickly include
+Articles in this Class.
+
+The Class needs to be set up and Applied for the dropdown to appear
+(see L</"Classes">).
 
 =head2 SelfService Interface
 
 If you grant the Unprivileged user group the right ShowArticle, they
 will get a Search box at the top of their interface.  This allows users
-to look for answer to questions before creating a Ticket.
+to look through your Articles for answers to questions before creating
+a Ticket.
 
-=head1 Configuration options
+=head1 Configuration Options
 
 =head2 ArticleOnTicketCreate
 
 Set this to a true value to display the Article include interface on the
 Ticket Create page in addition to the Reply/Comment page (Create.html
-in addition to Update.html)
+in addition to Update.html).
 
 =head2 HideArticleSearchOnReplyCreate
 
 On Ticket Reply (and Create if you set the above config var)
-RTFM normally displays a search box and an include box (for
-inputting an article id) and configurable dropdowns
-of articles.  These can be configured using Global Topics or
+RT's Article system normally displays a search box and an include box
+(for inputting an article id) and configurable dropdowns
+of Articles.  These can be configured using Global Topics or
 on the Class page.
 
-If you set this to a true value, RTFM will only display
-dropdowns and hide the search boxes
+If you set this to a true value, RT will only display
+dropdowns and hide the search boxes.
 
 =cut
diff --git a/rt/docs/extending/external_custom_fields.pod b/rt/docs/extending/external_custom_fields.pod
index c6730ae4e..f32bda769 100644
--- a/rt/docs/extending/external_custom_fields.pod
+++ b/rt/docs/extending/external_custom_fields.pod
@@ -13,7 +13,7 @@ For each type of data source that you want, you'll need to put a file in
 F</opt/rt4/local/lib/RT/CustomFieldValues/> (or equivalent if you
 installed RT into someplace other than F</opt/rt4>). To get a sense of
 the code that you'll need to write, take a look at the code in
-L</opt/rt4/lib/RT/CustomFieldValues/Groups.pm> for a simple example
+F</opt/rt4/lib/RT/CustomFieldValues/Groups.pm> for a simple example
 which just uses RT's API to pull in a list of RT's groups.
 
 Running C<perldoc /opt/rt4/lib/RT/CustomFieldValues/External.pm> will
diff --git a/rt/docs/hacking.pod b/rt/docs/hacking.pod
index 396c5623d..7c50ee901 100644
--- a/rt/docs/hacking.pod
+++ b/rt/docs/hacking.pod
@@ -38,7 +38,9 @@ For example, a bugfix branched from C<4.0-trunk> might be named
 C<4.0/fail-taint-mode-early>.  A feature branched from C<master> when
 there exists a C<4.0-trunk> but no C<4.2-trunk> might be named
 C<4.2/rename-LogToScreen>.  For consistency, branches should use dashes,
-not underscores, to separate words.
+not underscores, to separate words.  Branches which are destined for
+4.2, but which are branched from 4.0 (to provide for easy extraction as
+a 4.0 extension) should be named 4.2-on-4.0/branch-name.
 
 Branches should be reviewed by another developer before being merged.
 Reviewers should make sure that the branch accomplishes what it claims
diff --git a/rt/docs/web_deployment.pod b/rt/docs/web_deployment.pod
index 5d2cd4c00..5a9bd93a8 100644
--- a/rt/docs/web_deployment.pod
+++ b/rt/docs/web_deployment.pod
@@ -113,6 +113,11 @@ preference are ignored.  We suggest the C<prefork> MPM or FastCGI
 deployment if your privileged users are in a different timezone than the
 one the server is configured for.
 
+B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
+this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
+to start, to prevent difficulties sending mail from RT.  Change to
+C<SetHandler modperl>, as the example below uses.
+
     <VirtualHost rt.example.com>
         ### Optional apache logs for RT
         # ErrorLog /opt/rt4/var/log/apache2.error