[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