-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.
+See F<devel/docs/UPGRADING-4.0> for internals changes relevant to
+extension writers. The following is tailored to RT administrators:
-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).
+=head2 Common issues
-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.
+RT now defaults to a database name of rt4 and an installation root of
+/opt/rt4.
+
+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.
+
+RT::Extension::CustomField::Checkbox has been integrated into core, so you
+MUST uninstall it before upgrading. In addition, you must run
+/opt/rt4/etc/upgrade/4.0-customfield-checkbox-extension script to convert old
+data.
+
+=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 /opt/rt4/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
+ /opt/rt4/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.
+=over
+
+=item *
+
+The "Rights Delegation" and "Personal Groups" features have been removed.
-* The "Rights Delegation" and "Personal Groups" features have been removed.
+=item *
-* Replace the following code in templates:
+Replace the following code in templates:
[{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
{ $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.
- 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
-*******
-UPGRADING FROM 4.0.5 and earlier - Changes:
+=head2 Ticket content searches (full text search)
+
+Since 4.0.0, RT's ticket content search is disabled by default because of
+performance issues when used without full text indexing. For details on how to
+re-enable it with (or without) full text indexing, see
+F<docs/full_text_indexing.pod>.
+
+
+
+=head1 UPGRADING FROM 4.0.5 AND EARLIER
+
+=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
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.
+
+=head1 UPGRADING FROM 4.0.13 AND EARLIER
+
+=head2 Outgoing mail From: header
+
+The "Default" key of the C<$OverrideOutgoingMailFrom> config option now,
+as previously documented, only applies when no ticket is involved.
+Previously it was also used when a ticket was involved but the
+associated queue had no specific correspond address. In such cases the
+global correspond address is now used.
+
+The config option C<$SetOutgoingMailFrom> now accepts an email address
+as a value which will act as a global default. This covers the simple
+case of sending all bounces to a specific address, without the previous
+solution of resorting to defining all queues in
+$OverrideOutgoingMailFrom. Any definitions in the Override option
+(including Default) still take precedence. See
+L<RT_Config/$SetOutgoingMailFrom> for more information.
+
+=head2 Reminder statuses
+
+New reminders are now created in the "reminder_on_open" status defined in your
+lifecycles. For the default lifecycle, this means reminders will start as
+"open" instead of "new". This change is for consistency when a completed
+reminder is reopened at a later date. If you use custom lifecycles and added
+further transition restrictions, you may need to adjust the L<"reminder_on_open"
+setting|RT_Config/reminder_on_open> in your lifecycles.
+
+=head2 Bookmarks
+
+Previously, the list of Bookmarks on your homepage was unlimited (if you
+had 100 bookmarked tickets, you would see a 100 item list on your RT at
+a Glance). 'Bookmarked Tickets' now uses the same size limits as any
+other search on your homepage. This can be customized using the 'Rows
+per box' setting on your RT at a Glance configuration page.
+
+=head2 PostgreSQL 9.2
+
+If you are upgrading an RT from 3.8 (or earlier) to 4.0 on PostgreSQL
+9.2, you should make sure that you have installed DBD::Pg 2.19.3 or
+higher. If you start your upgrade without installing a recent-enough
+version of DBD::Pg RT will stop the upgrade during the 3.9.8 step and
+remind you to upgrade DBD::Pg. If this happens, you can re-start your
+upgrade by running:
+
+ /opt/rt4/sbin/rt-setup-database --action insert --datadir etc/upgrade/3.9.8/
+
+Followed by re-running make upgrade-database and answering 3.9.8 when
+prompted for which RT version you're upgrading from.
projects / freeside.git / blobdiff