[Rt-commit] r15262 - in rtfm/branches/2.4.0-releng: etc lib/RT/FM
falcone at bestpractical.com
falcone at bestpractical.com
Tue Aug 19 21:05:36 EDT 2008
Author: falcone
Date: Tue Aug 19 21:05:34 2008
New Revision: 15262
Added:
rtfm/branches/2.4.0-releng/UPGRADING.mysql
rtfm/branches/2.4.0-releng/etc/RTFM_Config.pm
Modified:
rtfm/branches/2.4.0-releng/ (props changed)
rtfm/branches/2.4.0-releng/MANIFEST
rtfm/branches/2.4.0-releng/README
rtfm/branches/2.4.0-releng/UPGRADING
rtfm/branches/2.4.0-releng/lib/RT/FM/Introduction.pod
Log:
- Merge //mirror/bps-public/rtfm/trunk to //mirror/bps-public/rtfm/branches/2.4.0-releng
Modified: rtfm/branches/2.4.0-releng/MANIFEST
==============================================================================
--- rtfm/branches/2.4.0-releng/MANIFEST (original)
+++ rtfm/branches/2.4.0-releng/MANIFEST Tue Aug 19 21:05:34 2008
@@ -123,7 +123,6 @@
inc/Module/Install/Metadata.pm
inc/Module/Install/RTx.pm
inc/Module/Install/RTx/Factory.pm
-inc/Module/Install/Substitute.pm
inc/Module/Install/Win32.pm
inc/Module/Install/WriteAll.pm
lib/RT/FM.pm
Modified: rtfm/branches/2.4.0-releng/README
==============================================================================
--- rtfm/branches/2.4.0-releng/README (original)
+++ rtfm/branches/2.4.0-releng/README Tue Aug 19 21:05:34 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/branches/2.4.0-releng/UPGRADING
==============================================================================
--- rtfm/branches/2.4.0-releng/UPGRADING (original)
+++ rtfm/branches/2.4.0-releng/UPGRADING Tue Aug 19 21:05:34 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/branches/2.4.0-releng/UPGRADING.mysql
==============================================================================
--- (empty file)
+++ rtfm/branches/2.4.0-releng/UPGRADING.mysql Tue Aug 19 21:05:34 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.
Added: rtfm/branches/2.4.0-releng/etc/RTFM_Config.pm
==============================================================================
--- (empty file)
+++ rtfm/branches/2.4.0-releng/etc/RTFM_Config.pm Tue Aug 19 21:05:34 2008
@@ -0,0 +1,19 @@
+# This module is intended to be used to set RTFM options.
+# It is loaded after RT_Config.pm
+#
+# This file is actually a perl module, so you can include valid
+# perl code, as well.
+#
+# The converse is also true, if this file isn't valid perl, you're
+# going to run into trouble. To check your SiteConfig file, use
+# this comamnd:
+#
+# perl -c /path/to/your/etc/RTFM_Config.pm
+
+# Set this to 1 to display the RTFM interface on the Ticket Create page
+# in addition to the Reply/Comment page.
+# This will only work with 3.8.1 or greater
+
+Set($RTFM_TicketCreate, 0);
+
+1;
Modified: rtfm/branches/2.4.0-releng/lib/RT/FM/Introduction.pod
==============================================================================
--- rtfm/branches/2.4.0-releng/lib/RT/FM/Introduction.pod (original)
+++ rtfm/branches/2.4.0-releng/lib/RT/FM/Introduction.pod Tue Aug 19 21:05:34 2008
@@ -3,45 +3,116 @@
=head2 Basics
-Staff 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.0 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.
+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.
-Grant some ACLs to your users and start creating articles.
+=head2 Creating Articles
-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.
+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.
-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.
+=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.
+
+=head1 Configuration options
-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).
+=head2 RTFM_Create
-=head2 Config options
+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)
-You can read about that in F<lib/RT/FM/Config.pod>
+Please note, this only works with RTFM 3.8.1 or greater
=cut
More information about the Rt-commit
mailing list