RT 4.0.13

6 files changed, 109 insertions, 42 deletions

diff --git a/rt/docs/UPGRADING-3.4 b/rt/docs/UPGRADING-3.4
index 89454bdef..20435829d 100644
--- a/rt/docs/UPGRADING-3.4
+++ b/rt/docs/UPGRADING-3.4
@@ -9,3 +9,10 @@ changed to "ModifyCustomField"
 Custom Fields now have an additional right, "ModifyCustomField".  This right
 governs whether a user can modify an object's custom field values for a
 particular custom field. This includes adding, deleting and changing values.
+
+=head1 UPGRADING FROM 3.3.2 AND EARLIER
+
+Viewing custom fields now requires the "SeeCustomField" right either globally
+or on a per-queue basis.  Global CFs are no longer visible to everyone and
+SeeQueue is no longer sufficient to view queue-level CFs.  You must grant the
+"SeeCustomField" right manually after upgrade.
diff --git a/rt/docs/UPGRADING-4.0 b/rt/docs/UPGRADING-4.0
index ad8d87b5f..687dfbc61 100644
--- a/rt/docs/UPGRADING-4.0
+++ b/rt/docs/UPGRADING-4.0
@@ -24,9 +24,13 @@ 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.
+F<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.
+
+If you deploy RT with mod_perl, Apache will no longer start with C<SetHandler>
+set to `perl-script`. F<docs/web_deployment.pod> contains the
+new configuration.
 
 
 =head2 RT_SiteConfig.pm
@@ -148,3 +152,40 @@ the following Mason templates, this feature will not function 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.
diff --git a/rt/docs/customizing/articles_introduction.pod b/rt/docs/customizing/articles_introduction.pod
index ea49b05de..73b5c334d 100644
--- a/rt/docs/customizing/articles_introduction.pod
+++ b/rt/docs/customizing/articles_introduction.pod
@@ -11,7 +11,7 @@ RT.  They are organized into classes and topics.
 The user interface to Articles is available from the Tools -> Articles
 menu.  Admin functionality can be found under Tools -> Configuration ->
 Articles.  Once configured, articles will become available for searching
-on the Reply/Comment page on tickets.  There are configuration variables
+on the Reply/Comment page on tickets.  There are L</"Configuration Options">
 to make Articles available on ticket creation.
 
 =head2 Basics
@@ -30,20 +30,24 @@ Classes are equivalent to RT's queues.  They can be created by going
 to Tools -> Configuration -> Articles -> Classes -> New Class.  Articles
 are assigned to one Class.  When you create Custom Fields for use with
 Articles, they will be applied Globally or to a Class, like Custom
-Fields are applied to a Queue in RT.  Each class also controls what
-information is included into a reply (such as the Class header and
-footer) and the Article.
+Fields are applied to a Queue in RT.
 
-Classes need to be Applied, just like a Custom Field by using the
-Applied To link.  You can apply them globally or on a queue-by-queue
-basis.
+A common use for Articles is to store frequently
+used replies for requestors, like troubleshooting steps or how to sign
+up for a new account. When you insert Article text, you may or may not
+want to include the Article name and summary, in addition to the content,
+when inserting the Article in a reply. You can control this behavior on
+the Class configuration page.
 
-hotlist.
+Classes need to be Applied, just like a Custom Field, by using the
+Applies To link on the Modify Class page (Tools -> Configuration ->
+Articles -> Classes, select the class to modify).  You can apply
+them globally or on a queue-by-queue basis.
 
 =head3 Topics
 
 You can also use Topics to organize your Articles.  While editing a
-Class, there is a Topic tab for Class specific Topics.  You can create
+Class, there is a Topics tab for Class-specific Topics.  You can create
 global Topics from the Global tab under Tools -> Configuration.
 
 When editing Topics, type the name (and optionally description) of the
@@ -53,9 +57,9 @@ tree of Topics should show up when creating or modifying articles in
 the class. These can be arbitrarily nested.
 
 Global Topics will be available for all Articles, regardless of their
-Class.  Articles can belong to both global and class-specific Topics.
+Class.  Articles can belong to both global and Class-specific Topics.
 
-Articles topics can be set from the 'Modify' screen for the article --
+Article topics can be set from the Modify screen for the article --
 simply select as many topics as you desire from the list at the bottom
 of the screen.
 
@@ -63,18 +67,20 @@ of the screen.
 
 Articles don't have a single "body" section for each
 article. Everything is a custom field (except for name, summary and
-some other basic metadata). So, you need to create some custom
-fields to hold the Article body and other data.  These Custom Fields
-should have "Applies To" be "RTFM Articles".
+some other basic metadata). So to put information on an
+Article, you need to create some custom fields to hold the Article
+body and other data.  When you create these new Custom Fields, set
+the Applies To field to Articles.
 
-Once you've created your custom fields, go into your classes and click
-on "Custom Fields" and add the Custom Fields you want to each class.
+Once you've created your Custom Fields, go into your Classes, click
+on Custom Fields, and add the Custom Fields you want to each Class.
 Alternatively, use the Applies To link from each Custom Field.
 
 =head2 Creating Articles
 
-You can create an article from scratch by going to Tools -> Articles ->
+You can create an Article from scratch by going to Tools -> Articles ->
 New Article and then picking which Class to create the Article under.
+You must have a Class to assign the new Article to.
 The Summary, Description and Custom Fields will all be searchable when
 including an Article and you can control what Custom Fields end up in
 your Ticket from the Class configuration page.
@@ -84,11 +90,11 @@ your Ticket from the Class configuration page.
 You can extract the body of a ticket into an article. Within RT, you
 should now see an "Extract to article" button in the upper right hand
 corner of RT's UI when working with tickets. When you click that
-button, RT will ask you which Class to create your new article in.
-Once you click on a class name, the Ticket's transactions will be
+button, RT will ask you which Class to create your new Article in.
+Once you click on a Class name, the Ticket's transactions will be
 displayed, along with a set of select boxes. For each transaction, you
 can pick which Custom Field that transaction should be extracted to.
-From there on in, it's just regular article creation.
+From there on in, it's just regular Article creation.
 
 =head2 Including an Article
 
@@ -97,14 +103,14 @@ is a UI widget that lets you search for and include Articles in
 your reply.  (They're editable, of course).  
 
 Articles can be included by searching for them, knowing the Id of the
-article, using the Article Hotlist and using the Queue specific
+article, using the Article Hotlist and using the Queue-specific
 dropdown.
 
-=head2 Queue Specific List of Articles 
+=head2 Queue-Specific List of Articles 
 
-You can use Topics to organize a set of Queue specific Articles.
+You can use Topics to organize a set of Queue-specific Articles.
 Simply create a global Topic called 'Queues' and then create Topics
-under Queues named after each of your Queues.  Within each Queue named
+under Queues named after each of your Queues.  Within each Queue-named
 Topic, create some Topics and then assign Articles to those
 sub-topics.  This creates a hierarchy like this:
 
@@ -118,38 +124,44 @@ offered a choice of Topic 1 and Topic 2 along with the searching.
 After choosing Topic 1 or Topic 2, you will be given a list of
 relevant articles to choose.
 
-Alternately, you can now implement this by applying a single class to
-your queue and using the L<Article Hotlist> feature described below.
+Alternately, you can now implement this by applying a single Class to
+your Queue and using the L</"Article Hotlist"> feature described below.
 
 =head2 Article Hotlist
 
-If you enable "All articles in this class are on dropdown on ticket
-reply page" option, there will be a dropdown on the Create or Update
-page which allows users to quickly include Articles.
+The Modify Class page has a checkbox labelled "All Articles in this
+class should be listed in a dropdown of the ticket reply page".
+If you select this for a Class, a dropdown will be available on the
+Ticket Create or Update page which allows users to quickly include
+Articles in this Class.
+
+The Class needs to be set up and Applied for the dropdown to appear
+(see L</"Classes">).
 
 =head2 SelfService Interface
 
 If you grant the Unprivileged user group the right ShowArticle, they
 will get a Search box at the top of their interface.  This allows users
-to look for answer to questions before creating a Ticket.
+to look through your Articles for answers to questions before creating
+a Ticket.
 
-=head1 Configuration options
+=head1 Configuration Options
 
 =head2 ArticleOnTicketCreate
 
 Set this to a true value to display the Article include interface on the
 Ticket Create page in addition to the Reply/Comment page (Create.html
-in addition to Update.html)
+in addition to Update.html).
 
 =head2 HideArticleSearchOnReplyCreate
 
 On Ticket Reply (and Create if you set the above config var)
-RTFM normally displays a search box and an include box (for
-inputting an article id) and configurable dropdowns
-of articles.  These can be configured using Global Topics or
+RT's Article system normally displays a search box and an include box
+(for inputting an article id) and configurable dropdowns
+of Articles.  These can be configured using Global Topics or
 on the Class page.
 
-If you set this to a true value, RTFM will only display
-dropdowns and hide the search boxes
+If you set this to a true value, RT will only display
+dropdowns and hide the search boxes.
 
 =cut
diff --git a/rt/docs/extending/external_custom_fields.pod b/rt/docs/extending/external_custom_fields.pod
index c6730ae4e..f32bda769 100644
--- a/rt/docs/extending/external_custom_fields.pod
+++ b/rt/docs/extending/external_custom_fields.pod
@@ -13,7 +13,7 @@ For each type of data source that you want, you'll need to put a file in
 F</opt/rt4/local/lib/RT/CustomFieldValues/> (or equivalent if you
 installed RT into someplace other than F</opt/rt4>). To get a sense of
 the code that you'll need to write, take a look at the code in
-L</opt/rt4/lib/RT/CustomFieldValues/Groups.pm> for a simple example
+F</opt/rt4/lib/RT/CustomFieldValues/Groups.pm> for a simple example
 which just uses RT's API to pull in a list of RT's groups.
 
 Running C<perldoc /opt/rt4/lib/RT/CustomFieldValues/External.pm> will
diff --git a/rt/docs/hacking.pod b/rt/docs/hacking.pod
index 396c5623d..7c50ee901 100644
--- a/rt/docs/hacking.pod
+++ b/rt/docs/hacking.pod
@@ -38,7 +38,9 @@ For example, a bugfix branched from C<4.0-trunk> might be named
 C<4.0/fail-taint-mode-early>.  A feature branched from C<master> when
 there exists a C<4.0-trunk> but no C<4.2-trunk> might be named
 C<4.2/rename-LogToScreen>.  For consistency, branches should use dashes,
-not underscores, to separate words.
+not underscores, to separate words.  Branches which are destined for
+4.2, but which are branched from 4.0 (to provide for easy extraction as
+a 4.0 extension) should be named 4.2-on-4.0/branch-name.
 
 Branches should be reviewed by another developer before being merged.
 Reviewers should make sure that the branch accomplishes what it claims
diff --git a/rt/docs/web_deployment.pod b/rt/docs/web_deployment.pod
index 5d2cd4c00..5a9bd93a8 100644
--- a/rt/docs/web_deployment.pod
+++ b/rt/docs/web_deployment.pod
@@ -113,6 +113,11 @@ preference are ignored.  We suggest the C<prefork> MPM or FastCGI
 deployment if your privileged users are in a different timezone than the
 one the server is configured for.
 
+B<NOTE>: RT 3.8 and below suggested use of C<SetHandler perl-script>;
+this is incorrect for RT 4, and (starting in RT 4.0.11) RT will refuse
+to start, to prevent difficulties sending mail from RT.  Change to
+C<SetHandler modperl>, as the example below uses.
+
     <VirtualHost rt.example.com>
         ### Optional apache logs for RT
         # ErrorLog /opt/rt4/var/log/apache2.error