[Rt-commit] rt branch, 4.2/convert-upgrading-4.2-to-pod, created. rt-4.1.17-199-gaafd797

Jim Brandt jbrandt at bestpractical.com
Wed Aug 7 09:45:58 EDT 2013


The branch, 4.2/convert-upgrading-4.2-to-pod has been created
        at  aafd79758e5ce87cd6bb6139782a03c16bf522de (commit)

- Log -----------------------------------------------------------------
commit 4cae93f2d6ff953c70eea64d1697b75717db2c0e
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Mon Aug 5 16:17:35 2013 -0400

    Convert UPGRADING-4.2 to POD

diff --git a/docs/UPGRADING-4.2 b/docs/UPGRADING-4.2
index 42c1581..36896be 100644
--- a/docs/UPGRADING-4.2
+++ b/docs/UPGRADING-4.2
@@ -1,165 +1,227 @@
-UPGRADING FROM RT 4.0.0 and greater
-
-* The $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.
-
-* The $LogToScreen config setting is now named $LogToSTDERR which better
-  describes what the log level controls.  Setting $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 $LogToSTDERR instead.
-
-* The link direction and type maps are consolidated into RT::Link.  If you
-  wrote local customizations or extensions utilizing %RT::Ticket::LINKDIRMAP,
-  %RT::Ticket::LINKTYPEMAP, RT::Ticket->LINKDIRMAP, RT::Ticket->LINKTYPEMAP, or
-  %RT::Record::LINKDIRMAP, you will need to switch to %RT::Link::DIRMAP and
-  %RT::Link::TYPEMAP.
-
-* $LinkTransactionsRun1Scrip is removed.  If you were relying on this behaviour
-  (by setting it to 1), you should adjust your scrips to ignore one of the link
-  transactions.
-
-* The $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.
-
-* MakeClicky handlers added via a callback are now passed an "object" key in
-  the parameter hash instead of "ticket".  The object may be any RT::Record
-  subclass.
-
-* $MessageBoxWrap was removed.  Wrapping is now always SOFT.  If you want hard
-  line breaks, enter them manually.
-
-* ShowUser handlers (/Elements/ShowUser*) have moved out of Mason components
-  and into RT::User methods.  Any custom username formats will need to be
-  reimplemented as RT::User methods.  Renaming should follow that of the core
-  components:
-
-        /Elements/ShowUserConcise => RT::User->_FormatUserConcise
-        /Elements/ShowUserVerbose => RT::User->_FormatUserVerbose
-
-  The _FormatUser* methods are passed a hash containing the keys User and
-  Address, which have the same properties as before.
-
-* Rich text (HTML) messages are now preferred for display.  If you prefer plain
-  text messages, set $PreferRichText to 0.
-
-* 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 $ValidateUserEmailAddresses to 0.
-
-* The 'smtp' value for $MailCommand, along with the associated
-  $SMTPServer, $SMTPFrom, and $SMTPDebug options, has been removed
-  because it did not guarantee delivery.  Instead, use a local MTA for
-  outgoing mail, via the 'sendmailpipe' setting to $MailCommand.
-
-* The @JSFiles config now only keeps additional JavaScript filenames; if
-  you had copied @JSFiles to add extra entries in your RT_SiteConfig,
-  remove the core JS from the list, or RT will serve those files
-  multiple times.
-
-* The $DeferTransactionLoading was combined into the new option $ShowHistory.
-  If you had enabled $DeferTransactionLoading, you may want to set $ShowHistory
-  to "click".  However, $ShowHistory provides a new mode, "delay", which is the
-  default and may be a more appealing alternative to "click".
-
-* A 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.
-
-* The Googleish search has been renamed to Simple. If you were
-  using this in an rt-crontool cronjob or had used a
-  Googleish_Local.pm to add features, you will need to convert to
-  using RT::Search::Simple instead.
-
-* RT was recording additional time change transactions during merge, so
-  difference in ticket's history doesn't add up value on ticket. This has
-  been fixed, time is adjusted during merge, but now transactions are recorded.
-
-  In order to fix history records of old ticket you can run the following
-  command:
+=head1 UPGRADING FROM RT 4.0.0 and greater
+
+=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 *
+
+The link direction and type maps are consolidated into RT::Link.  If you
+wrote local customizations or extensions utilizing C<%RT::Ticket::LINKDIRMAP>,
+C<%RT::Ticket::LINKTYPEMAP>, C<RT::Ticket-E<gt>LINKDIRMAP>,
+C<RT::Ticket-E<gt>LINKTYPEMAP>, or C<%RT::Record::LINKDIRMAP>, you will need to
+switch to C<%RT::Link::DIRMAP> and C<%RT::Link::TYPEMAP>.
+
+=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 *
+
+MakeClicky handlers added via a callback are now passed an "object" key in
+the parameter hash instead of "ticket".  The object may be any L<RT::Record>
+subclass.
+
+=item *
+
+C<$MessageBoxWrap> was removed.  Wrapping is now always C<SOFT>.  If you want hard
+line breaks, enter them manually.
+
+=item *
+
+C<ShowUser> handlers (C</Elements/ShowUser*>) have moved out of Mason components
+and into C<RT::User> methods.  Any custom username formats will need to be
+reimplemented as C<RT::User> methods.  Renaming should follow that of the core
+components:
+
+    /Elements/ShowUserConcise => RT::User->_FormatUserConcise
+    /Elements/ShowUserVerbose => RT::User->_FormatUserVerbose
+
+The C<_FormatUser*> methods are passed a hash containing the keys C<User> and
+C<Address>, which have the same properties as before.
+
+=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 *
+
+RT was recording additional time change transactions during merge, so
+the time difference in a ticket's history doesn't add up to the value on
+the ticket. This has been fixed. Time is adjusted during merge, but now
+transactions are not recorded.
+
+In order to fix the history records of old ticket you can run the following
+command:
 
     perl -I /opt/rt4/local/lib/ -I /opt/rt4/lib/ etc/upgrade/time-worked-history.pl
 
-  This command deletes records from Transactions table. This script can only fix
-  TimeWorked mismatch, but not TimeLeft or TimeEstimated.
-
-* 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.
-
-* CSS is no longer processed through Mason; it's served by a proper static file
-  handler.  If you used the Begin or End callbacks of main.css in the aileron,
-  web2, or ballard themes, you should transition to the @CSSFiles config option.
-  If you need to target specific themes, you can use the class set on the <body>
-  element (for example: body.aileron).  See docs/customizing/styling_rt.pd for
-  more information on custom styles.
-
-* There are now HTML versions of the standard plain text templates.  Running
-  make upgrade as described in the 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:
+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 *
+
+CSS is no longer processed through Mason; it's served by a proper static file
+handler.  If you used the C<Begin> or C<End> callbacks of C<main.css> in the
+aileron, web2, or ballard themes, you should transition to the
+L<RT_Config/@CSSFiles> config option. If you need to target specific themes,
+you can use the class set on the E<lt>C<body>E<gt> element (for example:
+body.aileron).  See F<docs/customizing/styling_rt.pod> for more information
+on custom styles.
+
+=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:
+To switch from HTML back to text, run:
 
     /opt/rt4/etc/upgrade/switch-templates-to text
 
-* The Articles menu is now a top-level menu item and display is controlled by
-  the right 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.
-
-* 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.
-
-* 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.
-
-* 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, the actions are available from the admin scrip pages.
-
-* 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.
-
-* On Oracle, sessions are now stored in the database by default instead of
-  on-disk.  If you wish to preserve the original behaviour, ensure the
-  following is in your RT_SiteConfig.pm:
-
-    Set($WebSessionClass, "Apache::Session::File");
-
-* Configuration options dealing with "external authentication" have been
-  renamed to reduce confusion with the common extension
-  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
-
-* Due to many long-standing bugs and limitations, the "Offline Tool" was
-  removed.
+=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, the actions are available from the admin scrip pages.
+
+=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>.
+
+=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.
+
+=back
+
+=cut

commit aafd79758e5ce87cd6bb6139782a03c16bf522de
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Wed Aug 7 09:43:07 2013 -0400

    Add intro text to UPGRADING-4.2 doc

diff --git a/docs/UPGRADING-4.2 b/docs/UPGRADING-4.2
index 36896be..fb98306 100644
--- a/docs/UPGRADING-4.2
+++ b/docs/UPGRADING-4.2
@@ -1,5 +1,12 @@
 =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.
+
 =over
 
 =item *

-----------------------------------------------------------------------


More information about the Rt-commit mailing list