--- /dev/null
+=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:
+
+ /opt/rt4/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:
+
+ /opt/rt4/etc/upgrade/switch-templates-to html
+
+To switch from HTML back to text, run:
+
+ /opt/rt4/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 Postgres; 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; GiST 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<GIN> indexes on C<Attachments>, and re-generate the index using
+C<rt-setup-fulltext-index>.
+
+=cut
projects / freeside.git / blobdiff