Merge branch '3.9-merge-rtfm' into 3.9-trunk

Conflicts:
	t/00-compile.t

UPGRADING.mysql.rtfm

@@ -0,0 +1,48 @@
+MySQL 4.1 and greater implemented changes in character set handling
+that may result in failures.  Since RT now has utf8 encoded tables,
+having old RTFM tables in the latin1 characterset will cause errors
+while using RTFM.
+
+In order to resolve this issue we've changed our schema for mysql 4.1 and greater
+versions.
+
+If this is a new install of RTFM on RT 3.8, you do not need to worry about this.
+
+If you're migrating from MySQL 4.0 to MySQL 4.1 and newer then you MUST follow
+instructions at the bottom of this file.
+
+If you're upgrading RTFM and RTFM was originally a version below 2.4.0 you
+MUST follow these instructions.
+
+=== Upgrading RT from versions prior to 3.8.0 ===
+
+1) Backup RT database. It's really good to test that you can restore from
+   this backup.
+
+2) Follow the README to step 4 (make install)
+
+3) Apply changes described in step 3 of UPGRADING
+
+4) Apply mysql 4.0->4.1 schema changes. RTFM tarball has script
+etc/upgrade/upgrade-mysql-schema.pl that generates SQL queries to upgrade schema of
+the DB. Run it:
+
+    perl etc/upgrade/upgrade-mysql-schema.pl db user pass > sql.queries
+
+5) Check sanity of sql queries yourself or consult with your DBA
+
+6) Apply queries. Note that this step can take a while. May require additional
+   space on your hard drive comparable with size of your tables.
+
+    mysql -u root -p rt3 < sql.queries
+
+NOTE that 'rt3' is the default name of the RT DB, change it in the command above
+if you're using different name.
+
+This step shouldn't produce any errors or warnings, but if you see some then revert
+DB from backup you made at step 1) and send report to the
+[email protected] mailing list.
+
+7) Return to the README at step 6 and set up your config and continue.
+
+8) Test everything. 

UPGRADING.rtfm

@@ -0,0 +1,97 @@
+Upgrade instructions (From any 2.2.x release)
+-----------------------------------------------------
+
+There were no database changes from 2.2 to 2.4
+you should be able to follow the normal
+installation instructions which will overwrite
+existing RTFM code with the 2.4 version.
+
+Do not run the make initdb command
+
+It is recommended that you make a backup of your
+/opt/rt3 directory in case there are problems
+
+After installing 2.4, stop and start your web
+server, clearing your mason cache if necesary.
+
+If you installed an earlier version of RTFM on
+mysql 4.0 and are now upgrading to 4.1 or higher,
+you need to upgrade the database tables types.
+This is similar to the process for RT.
+See UPGRADING.mysql
+
+Upgrade Instructions from 2.1.x
+-----------------------------------------------------
+
+1) perl Makefile.PL
+
+2) make install
+
+3) Type "ls etc/upgrade"; For each item in that directory whose name
+   is greater than your previously installed RTFM version, run:
+
+            /opt/rt3/sbin/rt-setup-database --action schema \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action acl \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action insert \
+                 --datadir etc/upgrade/<version>
+
+   For the 2.2.0RC2 updates and 2.1.30 updates you may need to
+   run these as a superuser because they issue ALTER TABLE statements.
+
+   You can do this by adding the --dba root --prompt-for-dba-password
+   flags, like so:
+
+            /opt/rt3/sbin/rt-setup-database --action schema \
+                --dba root --prompt-for-dba-password \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action acl \
+                --dba root --prompt-for-dba-password \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action insert \
+                --dba root --prompt-for-dba-password \
+                 --datadir etc/upgrade/<version>
+
+4) If you are running 3.8, you need to enable RTFM in your 
+   RT_SiteConfig.pm file.  You can do this by adding the following
+   line:
+
+   Set(@Plugins,qw(RT::FM));
+
+5) clear your mason cache.  This is most often accomplished with
+   rm -rf /opt/rt3/var/mason_data/*
+
+6) stop and start your web server
+
+
+Upgrade instructions (From any  2.0.x release):
+-----------------------------------------------------
+
+1) perl Makefile.PL
+
+2) perl -I/path/to/your/rt/lib etc/upgrade/migrate-2.0-to-2.1
+
+if you are installing 2.4.x on a new machine and have brought
+your old 2.0.x database over, you will need a copy of the
+RTFM 2.0 libs.  You can bring these from your old machine or
+download them from http://download.bestpractical.com
+This command would then be
+
+perl -I/path/to/your/old/rtfm/lib -I/path/to/rt/lib etc/upgrade/migrate-2.0-to-2.1
+
+3) Type "make install"
+
+4) Type "ls etc/upgrade"; For each item in that directory whose name
+   is greater than your previously installed RTFM version, run:
+
+            /opt/rt3/sbin/rt-setup-database --action schema \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action acl \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action insert \
+                 --datadir etc/upgrade/<version>
+
+5) See note in ugprading from 2.2.x about UPGRADING.mysql
+
+6) stop and start your web server

docs/articles_introduction.pod

@@ -0,0 +1,135 @@
+
+=head1 INTRODUCTION
+
+=head2 Basics
+
+Users should be now have a new "RTFM" menu item RT's top level menu.
+You will need to make some decisions about how to organize your
+articles.  Articles will be organized into one Class and multiple
+Topics.  They will use Custom Fields to store their article data.
+These Custom Fields can be configured on a Class by Class basis.
+
+=head2 Organization
+
+=head3 Classes
+
+Classes are equivalent to RT's queues.  They can be created by going
+to RTFM -> Configuration -> Classes -> New Class.  Articles are
+assigned to one Class.  When you create Custom Fields for use in RTFM,
+they will be activated per Class, like Custom Fields are activated per
+Queue in RT.  Each class also controls what information is included
+into a reply (such as the RTFM header and footer) and the Article
+hotlist.
+
+=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
+global Topics from the Global tab under RTFM -> Configuration.
+
+When editing Topics, type the name (and optionally description) of the
+Topic, and then click the button at the appropriate location in the
+Topic hierarchy. This should allow you to build a tree of Topics. This
+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.
+
+Articles 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.
+
+=head2 Custom Fields
+
+RTFM doesn'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".
+
+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.
+Alternatively, use the Applies To link from each Custom Field.
+
+=head2 Creating Articles
+
+You can create an article from scratch by going to RTFM -> Articles ->
+New Article and then picking which Class to create the Article under.
+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.
+
+=head3 Extracting an Article
+
+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, RTFM 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.
+
+=head2 Including an Article
+
+When replying to or commenting on tickets or creating tickets, there
+is a UI widget that lets you search for and include RTFM 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
+dropdown.
+
+=head2 Queue Specific List of 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
+Topic, create some Topics and then assign Articles to those
+sub-topics.  This creates a hierarchy like this:
+
+Queues
+\-> General
+    \-> Topic 1
+    \-> Topic 2
+
+If you are replying to a Ticket in the General Queue you will be
+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.
+
+=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.
+
+=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.
+
+=head1 Configuration options
+
+=head2 RTFM_TicketCreate
+
+Set this to a true value to display the RTFM include interface on the
+Ticket Create page in addition to the Reply/Comment page (Create.html
+in addition to Update.html)
+
+Please note, this only works with RTFM 3.8.1 or greater
+
+=head2 RTFM_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
+on the Class page.
+
+If you set this to a true value, RTFM will only display
+dropdowns and hide the search boxes
+
+=cut

etc/RT_Config.pm.in

@@ -1138,7 +1138,7 @@ Set($MessageBoxIncludeSignatureOnComment, 1);
 Support implicit links in WikiText custom fields?  A true value
 causes InterCapped or ALLCAPS words in WikiText fields to
 automatically become links to searches for those words.  If used on
-RTFM articles, it links to the RTFM article with that name.
+Articles, it links to the Article with that name.
 
 =cut
 
@@ -1537,6 +1537,10 @@ Set(%AdminSearchResultFormat,
         q{'<a href="__WebPath__/__WebRequestPathDir__/Template.html?Queue=__QueueId__&Template=__id__">__id__</a>/TITLE:#'}
         .q{,'<a href="__WebPath__/__WebRequestPathDir__/Template.html?Queue=__QueueId__&Template=__id__">__Name__</a>/TITLE:Name'}
         .q{,'__Description__'},
+    Classes =>
+        q{ '<a href="__WebPath__/Admin/Articles/Classes/Modify.html?id=__id__">__id__</a>/TITLE:#'}
+        .q{,'<a href="__WebPath__/Admin/Articles/Classes/Modify.html?id=__id__">__Name__</a>/TITLE:Name'}
+        .q{,__Description__},
 );
 
 =item C<$SuppressInlineTextFiles>
@@ -2180,7 +2184,7 @@ Set C<@Plugins> to a list of external RT plugins that should be enabled (those
 plugins have to be previously downloaded and installed).
 Example:
 
-C<Set(@Plugins, (qw(Extension::QuickDelete RT::FM)));>
+C<Set(@Plugins, (qw(Extension::QuickDelete RT::Extension::CommandByMail)));>
 
 =cut
 
@@ -2321,6 +2325,28 @@ This option is exists for backwards compatibility.  Don't use it.
 
 =cut
 
+=head1 Articles
+
+=item C<$ArticleOnTicketCreate>
+
+Set this to 1 to display the Articles interface on the Ticket Create page
+in addition to the Reply/Comment page.
+This will only work with 3.8.1 or greater
+
+=back
+
+=cut
+
+Set($ArticleOnTicketCreate, 0);
+
+=item C<$HideArticleSearchOnReplyCreate>
+
+=back
+
+=cut
+
+Set($HideArticleSearchOnReplyCreate, 0);
+
 =head1 DON'T MESS WITH THE STUFF BELOW
 
 =cut

etc/RT_SiteConfig.pm

@@ -19,6 +19,6 @@ Set( $rtname, 'example.com');
 # You must install Plugins on your own, this is only an example
 # of the correct syntax to use when activating them.
 # There should only be one @Plugins declaration in your config file.
-#Set(@Plugins,(qw(RT::Extension::QuickDelete RT::FM)));
+#Set(@Plugins,(qw(RT::Extension::QuickDelete RT::Extension::CommandByMail)));
 
 1;

etc/acl.Pg

@@ -46,6 +46,16 @@ sub acl {
         customfieldvalues_id_seq
         CustomFieldValues
         sessions
+        classes_id_seq
+        Classes
+        articles_id_seq
+        Articles
+        topics_id_seq
+        Topics
+        objecttopics_id_seq
+        ObjectTopics
+        objectclasses_id_seq
+        ObjectClasses
     );
 
     my $db_user = RT->Config->Get('DatabaseUser');

etc/rtfm/upgrade/2.1.0/acl.Oracle

@@ -0,0 +1,4 @@
+sub acl {
+    return ();
+}
+1;

etc/rtfm/upgrade/2.1.0/acl.Pg

@@ -0,0 +1,24 @@
+
+sub acl {
+    my $dbh = shift;
+
+    my @acls;
+
+    my @tables = qw (
+FM_Topics_id_seq
+FM_Topics
+FM_ObjectTopics_id_seq
+FM_ObjectTopics
+    );
+
+    foreach my $table (@tables) {
+        push @acls,
+          "GRANT SELECT, INSERT, UPDATE, DELETE ON $table to "
+          . $RT::DatabaseUser . ";";
+
+    }
+    return (@acls);
+}
+1;
+
+