=head1 UPGRADING FROM RT 4.0.0 and greater

The 4.2 release is a major upgrade and as such there are more changes
than in a minor bugfix release (e.g., 4.0.13 to 4.0.14) and some of these
changes are backward-incompatible. The following lists some of the notable
changes, especially those that might require you to change a configuration
option or other setting due to a change in RT.  Read this section carefully
before you upgrade and look for changes to features you currently use.

See F<devel/docs/UPGRADING-4.0> for internals changes relevant to
extension writers.

=over

=item *

The L<RT_Config/$UseSQLForACLChecks> option defaults to on.  This provides
a number of improvements, most notably no longer showing pages of empty results
if the user doesn't have permissions to view the tickets in question.
It may, in some cases, have performance impacts, but these have been
found to be minimal in existing 4.0 installs.

=item *

The C<$LogToScreen> config setting is now named
L<< "C<$LogToSTDERR>"|RT_Config/"$LogToSyslog, $LogToSTDERR" >> which
better describes what the log level controls.  Setting C<$LogToScreen> will
still work, but an informational notice will be issued on server start telling
you about the rename.  To avoid this you should set C<$LogToSTDERR> instead.

=item *

C<$LinkTransactionsRun1Scrip> is removed.  If you were relying on this behavior
(by setting it to 1), you should adjust your scrips to ignore one of the link
transactions.

=item *

The C<$AttachmentUnits> option was removed in preference of always displaying in
megabytes, kilobytes, or bytes as appropriate.  The option was incompletely
implemented and controlled display in the attachments list but not history.

=item *

C<$MessageBoxWrap> was removed.  Wrapping is now always C<SOFT>.  If you want hard
line breaks, enter them manually.

=item *

Rich text (HTML) messages are now preferred for display.  If you prefer plain
text messages, set L<RT_Config/$PreferRichText> to 0.

=item *

User email addresses are now validated by default and multiple,
comma-separated addresses for a single user are no longer allowed.  Existing
users with invalid addresses will continue to work until the next time they
are updated by an administrator on the modify user page.  If you prefer no
address validation, set L<RT_Config/$ValidateUserEmailAddresses> to 0.

=item *

The C<smtp> option for L<RT_Config/$MailCommand>, along with the associated
C<$SMTPServer>, C<$SMTPFrom>, and C<$SMTPDebug> options, has been removed
because it did not guarantee delivery.  Instead, use a local MTA for
outgoing mail, via the 'sendmailpipe' setting to C<$MailCommand>.

=item *

The L<RT_Config/@JSFiles> config now only keeps additional JavaScript filenames; if
you had copied C<@JSFiles> to add extra entries in your C<RT_SiteConfig.pm>,
remove the core JS from the list, or RT will serve those files
multiple times.

=item *

The C<$DeferTransactionLoading> option was combined into the new option
L<RT_Config/$ShowHistory>. If you had enabled C<$DeferTransactionLoading>,
you may want to set C<$ShowHistory> to C<click>.  However, C<$ShowHistory>
provides a new mode, C<delay>, which is the default and may be a more
appealing alternative to C<click>.

=item *

A C<Status> transaction is now recorded when a ticket status changes as a
result of a queue change.  Scrips with conditions relying on Status changes
may start to trigger on these transitions; previously these Status changes
never triggered scrips.

=item *

The C<Googleish> search has been renamed to C<Simple>. If you were
using this in an L<< C<rt-crontool> >> cronjob or had used a
C<Googleish_Local.pm> to add features, you will need to convert to
using L<RT::Search::Simple> instead.

=item *

On merge, RT retains transactions from both tickets. Previously, RT
also recorded explicit time change transactions during a
merge to adjust the total time spent. This caused the total time
spent, as summed from transactions, to be different from the ticket's
overall time spent. This has been fixed: time is adjusted during the
merge commit itself, removing the need for the confusing
extra transactions, and keeping the summed time spent consistent.

In order to fix the history records of old ticket you can run the following
command:

    /usr/share/request-tracker5/etc/upgrade/time-worked-history

This command deletes records from the Transactions table. This script can only fix
TimeWorked mismatches, but not TimeLeft or TimeEstimated.

=item *

A new action, "Open Inactive Tickets", has been added, and on new
installs the default scrip "On Correspond Open Tickets" has been
replaced by "On Correspond Open Inactive Tickets".  The key difference
between "Open Tickets" and "Open Inactive Tickets" is that the latter
will not adjust the status of a ticket if it is already active.  This
is particularly useful when creating complex workflows using
Lifecycles.

=item *

There are now HTML versions of the standard plain text templates.  Running
make upgrade as described in the F<README> will insert the new templates into
existing installs.  While new installs use the HTML templates by default,
upgrades from older versions don't automatically switch to the HTML versions.
To switch existing scrips, run:

    /usr/share/request-tracker5/etc/upgrade/switch-templates-to html

To switch from HTML back to text, run:

    /usr/share/request-tracker5/etc/upgrade/switch-templates-to text

=item *

The Articles menu is now a top-level menu item and display is controlled by
the right C<ShowArticlesMenu>.  This right is only grantable globally to groups
or users.  During the upgrade, the new right will be automatically granted to
Privileged users so that the menu doesn't disappear for anyone previously
using it.  You may wish to revoke the right from Privileged and grant it
more selectively.

=item *

The Owner drop-down now only includes privileged users (no matter if
unprivileged users have been granted the OwnTicket right) because
configurations which have unprivileged Owners are exceedingly rare,
and granting Everyone the OwnTicket right is a common cause of
performance problems.  Unprivileged Owners (if they exist) may still
be set using the Autocompleter.

=item *

The functionality that changed the ticket status to Open when the Started
date is set has been moved to a Scrip called 'On transaction and SetStarted
Open Ticket'. If you do not depend on this functionality, the Scrip can
be deleted.

=item *

New installs will notify Ccs and one-time Ccs/Bccs on create and Owners on
create and correspond.  Upgraded installations will not.  If you'd like to
adjust your scrips to match the new install behavior, create and edit the
following scrips from the admin scrip page:

To notify Ccs on create, on the 'Create a global scrip' page:

  Description: On Create Notify Ccs
  Condition:   On Create
  Action:      Notify Ccs
  Template:    Correspondence in HTML

To notify one-time Ccs/Bccs on create, on the 'Create a global scrip' page:

  Description: On Create Notify Other Recipients
  Condition:   On Create
  Action:      Notify Other Recipients
  Template:    Correspondence in HTML

To notify Owners on create, click 'On Create Notify AdminCcs'. Change the
fields listed below to their corresponding values:

  Description: On Create Notify Owner and AdminCcs
  Action:      Notify Owner and AdminCcs

To notify Owners on correspond, click 'On Correspond Notify AdminCcs'. Change
the fields listed below to their corresponding values:

  Description: On Correspond Notify Owner and AdminCcs
  Action:      Notify Owner and AdminCcs

=item *

Notifications to AdminCcs on approvals are now handled via the New Pending
Approval template in the hidden ___Approvals queue.  If you customized the
Transaction template, you should port your changes to New Pending Approval.

=item *

On Oracle, sessions are now stored in the database by default instead of
on-disk.  If you wish to preserve the original behavior, ensure that
L<RT_Config/$WebSessionClass> is set in your C<RT_SiteConfig.pm>:

    Set($WebSessionClass, "Apache::Session::File");

=item *

Configuration options dealing with "external authentication" have been
renamed to reduce confusion with the common extension
L<RT::Authen::ExternalAuth>.  The old names will work, but produce
deprecation warnings.  The old names, and their new counterparts, are:

    WebExternalAuth           => WebRemoteUserAuth
    WebExternalAuthContinuous => WebRemoteUserContinuous
    WebFallbackToInternalAuth => WebFallbackToRTLogin
    WebExternalGecos          => WebRemoteUserGecos
    WebExternalAuto           => WebRemoteUserAutocreate
    AutoCreate                => UserAutocreateDefaultsOnLogin

=item *

Due to many long-standing bugs and limitations, the "Offline Tool" was
removed.

=item *

To increase security against offline brute-force attacks, RT's default
password encryption has been switched to the popular bcrypt() key
derivation function.  Passwords cannot be automatically bulk upgraded to
the new format, but will be replaced with bcrypt versions upon the first
successful login.

=item *

We updated default "Forward" and "Forward Ticket" templates to support
customizing messages on forward. They will be updated automatically if you
didn't change them before.

But in case you have changed them already, you need to update them manually.
You can use $ForwardTransaction to refer to the customized message in the
templates, e.g. "Forward" template could be updated to:

{ $ForwardTransaction->Content =~ /\S/ ? $ForwardTransaction->Content : "This is a forward of transaction #".$Transaction->id." of ticket #". $Ticket->id }

=item *

RT has generated RT-Ticket: RT-Originator: and Managed-By: headers in
compliance with RFC2822/6648 but we've discovered that some smarthost
providers are requiring strict adherence to RFC822 which mandates X-
prefixes on these headers. We've made this change in 4.2 for users
relying on those providers.

Any external scripts which were parsing on these RT mail headers will
need to be updated.

=item *

GnuPG and S/MIME are no longer enabled in F<RT_Config.pm> merely by the
presence of the C<gpg> or C<openssl> binaries.  Systems which depended
on C<configure> enabling these in F<RT_Config.pm> implicitly will need
to pass C<--enable-gpg> to C<configure>, or alter their
C<RT_SiteConfig.pm> to enable the functionality explicitly.

=item *

In TicketSQL, "Starts = '1970-01-01'" will no longer find tickets with
no Starts date set.  Instead, use "Starts IS NULL".  As a direct
consequence, "Starts < 'today'" will no longer also find tickets with no
Starts date; use "Starts < 'today' OR Starts IS NULL" to have the
equivalent results in RT 4.2.

=back

=head1 UPGRADING FROM 4.2.3 AND EARLIER

RT 4.2.4's upgrade scripts contain two fixes to normalize upgraded RTs
with those installed new from a release of RT 4.2.

We neglected to add the "Open Inactive Tickets" action mentioned earlier
in this documents. It was available to fresh installs but not on
upgrades. This Scrip Action is now created if needed.

RT expects the ___Approvals queue to have a special value in the
Disabled column so that it is hidden B<but> tickets can still be created
(normal disabled Queues disallow ticket creation).  Users who enabled
and then disabled the Queue on earlier releases will have the incorrect
Disabled value, so we fix that.  A similar problem applies to the
lifecycle, which must be set to the internal "approvals" lifecycle --
which is not listed as an option.  RT 4.2.4 also includes enhancements
to the Queue admin page for ___Approvals to prevent editing things which
might cause problems.

=head1 UPGRADING FROM 4.2.5 AND EARLIER

RT 4.2.6 includes a new Scrip Action "Notify Owner or AdminCc". This
action will send the given correspondence to the Owner, if not Nobody,
otherwise it will notify the AdminCcs. If using this, you will likely
want to modify or remove the Notify Owner and AdminCcs scrip to avoid
duplicate notifications. This Scrip Action is not used in any default
Scrips at this time.

=head1 UPGRADING FROM 4.2.6 AND EARLIER

The C<$LogoImageHeight> and C<$LogoImageWidth> configuration options
have been overridden by CSS since 4.0.0, and thus did not affect
display.  They have been removed, and setting them will trigger an
informational message that setting them is ineffective.

=head1 UPGRADING FROM 4.2.9 AND EARLIER

An additional optional dependency, L<HTML::FormatExternal>, has been
added.  This allows RT to use C<w3m>, C<elinks>, C<html2text>, or other
external tools to render HTML to text.  This dependency is not installed
by default; however, its use is strongly encouraged, and will resolve
issues with blank outgoing emails.

=head1 UPGRADING FROM 4.2.10 AND EARLIER

The C<$DatabaseRequireSSL> option has never affected whether the
database connection was performed using SSL, even under PostgreSQL; the
functionality can now be implemented via C<%DatabaseExtraDSN>.
C<$DatabaseRequireSSL> has been removed, and setting it will trigger an
informational message that setting it is ineffective.

The full-text indexing defaults for PostgreSQL have changed; GIN is now
the suggested index, as well as storing data in a separate
AttachmentsIndex table.  Both changes improve lookup speed.  For
improved search performance, you may wish to drop existing C<tsvector>
and C<GiST> indexes on C<Attachments>, and re-generate the index using
C<rt-setup-fulltext-index>.

=head1 UPGRADING FROM 4.2.12 AND EARLIER

New deployments install an C<RT_SiteConfig.pm> that includes a C<use utf8;>
to allow Unicode to be used in config. You may wish to add a C<use utf8;> to
the top of your C<RT_SiteConfig.pm> if you haven't already done so.

=cut