[Rt-commit] r15258 - rtfm/trunk

falcone at bestpractical.com falcone at bestpractical.com
Tue Aug 19 20:54:13 EDT 2008


Author: falcone
Date: Tue Aug 19 20:54:12 2008
New Revision: 15258

Added:
   rtfm/trunk/UPGRADING.mysql
Modified:
   rtfm/trunk/   (props changed)
   rtfm/trunk/README
   rtfm/trunk/UPGRADING

Log:
 r38611 at ketch:  falcone | 2008-08-19 19:55:40 -0400
 * move the introduction out of the readme
 * steal ruz's upgrade instructions for RTFM
 * document how to upgrade RTFM 
   * add notes about upgrading mysql + RTFM


Modified: rtfm/trunk/README
==============================================================================
--- rtfm/trunk/README	(original)
+++ rtfm/trunk/README	Tue Aug 19 20:54:12 2008
@@ -18,10 +18,11 @@
 
 NOTE that upgrade steps are described in UPGRADING
 
-1) Install RT 3.4.2 or newer
+1) Install RT 3.4.2 or newer (Do not use this with 3.8.0 as
+   there are incompatibilities)
 
-2) Once RT appears to be happily installed, cd into the directory you
-   unpacked RTFM into.
+2) Once RT appears to be happily installed, cd into the directory
+   where you unpacked RTFM.
 
 3) perl Makefile.PL
 
@@ -35,10 +36,10 @@
 
    Set(@Plugins,qw(RT::FM));
 
-7) clear your mason cache.  This is most often accomplished with
+7) Clear your mason cache.  This is most often accomplished with
    rm -rf /opt/rt3/var/mason_data/*
 
-8) stop and start your web server
+8) Stop and start your web server
 
 9) Before you can add content to RTFM articles, you will need to configure
    classes and custom fields. For details, see lib/RT/FM/Introduction.pod
@@ -46,10 +47,10 @@
 Further reading:
 -----------------------------------------------------
 
-You can read pod files using perldoc utility that comes with perl.
-1) lib/RT/FM/Introduction.pod - quick overview
-2) lib/RT/FM/Config.pod - RTFM's config options
+lib/RT/FM/Introduction.pod - quick overview and configuration
 
+You can read this using the perldoc utility, viewing the
+source or using the RT-OnlineDocs extension
 
 Development
 ------------------------------------------------------
@@ -63,92 +64,11 @@
 
 RT_DBA_USER=user RT_DBA_PASSWORD=password PERL5LIB=/opt/rt3/lib make test
 
-Users should be now have a new "RTFM" menu item RT's top level menu.
-As an administrator, you should go create some "Classes" of articles in RTFM.
-Classes are equivalent to RT's queues. 
-
-Unlike RTFM 1.0, RTFM 2 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 go create some custom fields.
-
-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.
-
-Each Article will belong to a particular Class, but Articles can also be
-grouped using Topics.  Topics are created by administrators on Classes
-using the 'Topics' submenu of the RTFM Class configuration.  The
-configuration screen for the Class has a tab for '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.
-
-Topics can also be created globally.  These are managed from 
-RTFM's Configuration tab, under the Global heading along with
-global User and Group rights.  These 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.
-
-Of course, RTFM integrates with RT.  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 Freeform, Text, or
-WikiText field that transaction should be extracted to. From there on
-in, it's just regular article creation.  And the integration doesn't
-stop there!  When replying to or commenting on tickets, there is a UI
-widget that lets you search for and include RTFM articles in your reply.
-(They're editable, of course).  
-
-You can also bind articles to topics. Topics are created by administrators
-on classes using the 'Topics' submenu of the RTFM class configuration.
-The configuration screen for the class has a tab for 'topics'. Typing the
-name (and optionally description) of the topic, and then clicking the button
-at the appropriate location. 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 categories.
-
-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.
-
-Of course, RTFM integrates with RT.  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 Freeform, Text,
-or WikiText field that transaction should be extracted to. From there
-on in, it's just regular article creation.  And the integration
-doesn't stop there! When replying to or commenting on tickets, there's
-a new UI widget that lets you search for and include RTFM articles in
-your reply. (They're editable, of course).
-
-New in 2.4, 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.
+These are intended to be run before installing RTFM.
+Like RT, RTFM expects to be able to create a new database called rt3test
+on your system.
 
-Bugs reporting and discussion lists:
+Bug reporting and discussion lists:
 -----------------------------------------------------
 
 You probably want to discuss RTFM on rt-users at lists.bestpractical.com.
@@ -157,8 +77,3 @@
 Bug reports can be sent to rtfm-bugs at bestpractical.com. You can look
 at open bug reports at http://rt3.fsck.com/. Log in as guest/guest
 to see the content of bug reports.
-
-        Best,
-        Jesse Vincent
-        Best Practical Solutions, LLC
-

Modified: rtfm/trunk/UPGRADING
==============================================================================
--- rtfm/trunk/UPGRADING	(original)
+++ rtfm/trunk/UPGRADING	Tue Aug 19 20:54:12 2008
@@ -14,6 +14,12 @@
 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
 -----------------------------------------------------
 

Added: rtfm/trunk/UPGRADING.mysql
==============================================================================
--- (empty file)
+++ rtfm/trunk/UPGRADING.mysql	Tue Aug 19 20:54:12 2008
@@ -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 the seven step, but only up to version 3.8.0.
+
+4) Apply mysql 4.0->4.1 schema changes. RTFM tarball has script
+etc/upgrade/schema.mysql-4.0-4.1.pl that generates SQL queries to upgrade schema of
+the DB. Run it:
+
+    perl etc/upgrade/schema.mysql-4.0-4.1.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
+rt-users at lists.bestpractical.com mailing list.
+
+7) Return to the README at step 6 and set up your config and continue.
+
+8) Test everything. 


More information about the Rt-commit mailing list