X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2Fdocs%2FUPGRADING-4.0;h=0a3249c3ffa4e25960cc625b8449c46581e06e97;hp=4b64d2e725e709e2e9cf0f897385f29eaa1509ee;hb=681a340f6be4184b1472a8e1fa9cd5d074f6f325;hpb=85e677b86fc37c54e6de2b06340351a28f5a5916 diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0 index 4b64d2e72..0a3249c3f 100644 --- a/rt/docs/UPGRADING-4.0 +++ b/rt/docs/UPGRADING-4.0 @@ -1,87 +1,102 @@ -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 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 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 +set to `perl-script`. F 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}] @@ -89,38 +104,53 @@ 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. - 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. + + + +=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 @@ -129,3 +159,89 @@ 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. + +=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 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.