1 files changed, 108 insertions, 0 deletions
diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0
new file mode 100644
index 000000000..a9301348e
--- /dev/null
+++ b/rt/docs/UPGRADING-4.0
@@ -0,0 +1,108 @@
+Common Issues
+
+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:
+
+    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
+`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
+
+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.
+
+*******
+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.
+
+*******
+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.
+
+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.
+
+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.
+
+* Replace the following code in templates:
+
+    [{$Ticket->QueueObj->SubjectTag || $rtname} #{$Ticket->id}]
+
+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
+
+    /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.
+
+  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.
+
+*******