582 lines
22 KiB
Text
582 lines
22 KiB
Text
####################################################################
|
|
# WebGUI Upgrade Gotchas #
|
|
####################################################################
|
|
|
|
This file contains a list of any changes you should be aware of when
|
|
upgrading from one version to the next, or even between multiple
|
|
versions. Be sure to heed the warnings contained herein as they will
|
|
save you many hours of grief.
|
|
|
|
6.99.0
|
|
--------------------------------------------------------------------
|
|
|
|
* The 6.99 series is the last round of changes before 7.0.0 is
|
|
released. It will serve as the beta, gamma, and release
|
|
candidates for 7.0.0.
|
|
|
|
* The "messageLog" table will be deleted during the upgrade process,
|
|
and all of the messages in it. This is because the messages
|
|
contained in there are no longer useful because they won't
|
|
work with the new workflow system. If you need the data in
|
|
that table, you should save it before performing the upgrade.
|
|
|
|
* The session system has been replaced by a new object-oriented one,
|
|
which has caused massive API changes. Please consult
|
|
migration.txt to bring your custom code up to date with the
|
|
new API.
|
|
|
|
* You need to upgrade to the latest 6.8 release before you can
|
|
upgrade to 6.99.
|
|
|
|
* If you wish to use one of the new optional template engines
|
|
you'll need to install the perl modules for them:
|
|
|
|
Template
|
|
HTML::Template::Expr
|
|
|
|
* In order to make the upgrades run quickly, the upgrade process
|
|
will not automatically index your sites for the new search
|
|
engine. You need to do this manually after the upgrades
|
|
have completed by running the search.pl script in the
|
|
sbin folder.
|
|
|
|
* The following perl modules are now required:
|
|
|
|
MIME::Tools
|
|
POE
|
|
POE::Component::IKC::Server
|
|
POE::Component::Client::UserAgent
|
|
Net::Subnets
|
|
DateTime::Format::Mail
|
|
Net::POP3
|
|
List::Util
|
|
Color::Calc
|
|
|
|
* The upgrade script is going to convert your WebGUI config files
|
|
from the current PlainConfig format to the new JSON format.
|
|
Don't be alarmed by this, it's a normal part of the upgrade
|
|
procedure.
|
|
|
|
* You no longer need the cron job for runHourly.pl. Instead, you
|
|
must start sbin/spectre.pl when your server starts up.
|
|
Spectre is WebGUI's offline execution engine. It triggers
|
|
scheduled events and executes workflow tasks. Be sure to
|
|
edit each of your WebGUI config files to set the
|
|
spectreSubnet setting to match your IP address or IP range.
|
|
|
|
* If you wish to run the full test suite, you'll need to install
|
|
these optional modules:
|
|
|
|
Test::Deep
|
|
Test::MockObject
|
|
|
|
* The content in the import node has had inappropriate privileges
|
|
since it was created. We're resetting the privileges to be
|
|
viewable by everyone and editable by the turn admin on
|
|
group. If this is not what you want for your site, or for
|
|
segments of the content in your import node, you'll need
|
|
to change it after the upgrade.
|
|
|
|
* Because collaboration system posts are now integrated with
|
|
the workflow engine, the approve/deny links are no longer
|
|
needed or used in your templates. In addition if you wish
|
|
to use an approval process on any of your collaboration
|
|
systems, you'll need to re-enable it after this upgrade.
|
|
|
|
|
|
6.8.4
|
|
--------------------------------------------------------------------
|
|
* The If macro has been removed because it's far too dangerous and
|
|
error prone. If you use the If macro you may continue to use
|
|
it at your own risk, maintenance, and support cost, but it
|
|
is no longer supported by Plain Black.
|
|
|
|
|
|
|
|
|
|
6.8.1
|
|
--------------------------------------------------------------------
|
|
* Before upgrading you must install the following new Perl modules:
|
|
Data::Structure::Util
|
|
|
|
* Fixed a major versioning system bug in this release where when purging
|
|
the last revision of an asset, if it had children, the children were
|
|
not purged with it. This may have caused problems in some people's
|
|
databases if they used any 6.7.x version or 6.8.0. If it has all you
|
|
need to do to fix it is upgrade to this release and then run
|
|
sbin/rebuildLineage.pl
|
|
|
|
|
|
6.8.0
|
|
--------------------------------------------------------------------
|
|
* Before upgrading you must install the following new Perl modules:
|
|
DateTime
|
|
DateTime::Format::Strptime
|
|
DateTime::Cron::Simple
|
|
JSON
|
|
Finance::Quote
|
|
Archive::Zip
|
|
|
|
And optionally, these:
|
|
|
|
Test::More
|
|
Pod::Coverage
|
|
|
|
* If you have previously installed the community contributed version
|
|
of the In/Out Board (IOB) then you will need to completely
|
|
uninstall it before you can proceed with this upgrade.
|
|
|
|
* The core API has changed. Check docs/migration.txt for details.
|
|
|
|
* WebGUI now requires Apache2 with mod_perl2 so CGI, FastCGI, PerlEx,
|
|
although never officially supported, are no longer possible.
|
|
Making this change gave us more than 70% performance improvement
|
|
and opens up even more possibilities for performance and other
|
|
optimizations.
|
|
|
|
You'll need to make the following changes in Apache to upgrade
|
|
to this release:
|
|
|
|
Install libapreq2. You can either download and compile this
|
|
from the mod_perl web site, CPAN as Apache2::Request, or by
|
|
getting the version of the WRE 0.6.0 or higher.
|
|
|
|
Edit your httpd.conf or httpd.modperl.conf and add the following
|
|
directives to your global server config:
|
|
|
|
LoadModule apreq_module modules/mod_apreq2.so
|
|
PerlSetVar WebguiRoot /data/WebGUI
|
|
|
|
You may also remove this block if you have it:
|
|
|
|
<Files ~ "\.(pl)$">
|
|
SetHandler perl-script
|
|
PerlHandler ModPerl::Registry::handler
|
|
PerlOptions +ParseHeaders
|
|
</Files>
|
|
|
|
You also no longer need the ExecCGI directive.
|
|
|
|
Edit each of your virtual hosts and add the following directives,
|
|
changing them to suit your needs:
|
|
|
|
SetHandler perl-script
|
|
PerlInitHandler WebGUI
|
|
PerlSetVar WebguiConfig www.example.com.conf
|
|
|
|
If you were using mod rewrite you'll need to adjust your rules
|
|
because they no longer need to remove the gateway (index.pl)
|
|
from the URL.
|
|
|
|
If you were using the uploadsAccessHandler.perl you no longer
|
|
need that as it is built in to the WebGUI handler.
|
|
|
|
For more information consult the WebGUI Done Right documentation.
|
|
|
|
* WebGUI now requires MySQL 5.0 to operate. This is due to the huge
|
|
number of new features afforded us in the MySQL 5.0 database,
|
|
which will increase performance, and add to our functionality
|
|
for the future.
|
|
|
|
* WebGUI now requires Perl 5.8 to operate.
|
|
|
|
* The Macro API has been changed. If you have any third-party macros
|
|
installed make sure to update them prior to upgrading. See
|
|
docs/migration.txt for details.
|
|
|
|
* You may now optionally create sbin/preload.exclude with a carriage
|
|
return seperated list of modules you don't want to be preloaded.
|
|
This file requires each line to contain exactly one full module
|
|
name such as "WebGUI::Asset::Wobject::WSClient" (without the
|
|
quotes) per line. No spaces or additional formatting can be
|
|
present. You may, for example, just copy sbin/preload.exclude.example
|
|
to sbin/preload.exclude and save yourself about 5MB of memory
|
|
because that will eliminate some of the least commonly used
|
|
components.
|
|
|
|
If you mistakenly exclude modules that WebGUI actually needs
|
|
to run, it will load them at run time, and just use more RAM,
|
|
so you don't need to worry about breaking WebGUI. However, this
|
|
doesn't mean you should just exclude everything because doing
|
|
runtime loading will likely use 5-10 times more RAM than just
|
|
preloading them to begin with.
|
|
|
|
|
|
6.7.0
|
|
--------------------------------------------------------------------
|
|
* In order to upgrade to 6.7 you must first upgrade to at least 6.6.1.
|
|
|
|
* The asset API has changed slightly due to versioning, so if you
|
|
have any custom assets, check out migration.txt to make
|
|
sure they will comply.
|
|
|
|
|
|
* The templates for Survey assets has changed a little. After
|
|
upgrading you will notice that your custom view templates
|
|
will not display your questions for editing in Admin mode.
|
|
You will need to put your questions loop inside of a section
|
|
loop. See the default view template for an example.
|
|
|
|
* If you have any SQL reports going against the asset table, note that
|
|
it has been split into two tables "asset" and "assetData" and
|
|
your SQL reports will need to change.
|
|
|
|
* The indexed search asset has been disabled until 6.8 where it will
|
|
be entirely rewritten from the ground up.
|
|
|
|
|
|
6.6.4
|
|
--------------------------------------------------------------------
|
|
* Please ensure you're running HTML::Template version 2.7, which
|
|
supports javascript escaping and is needed to ensure js
|
|
menus work everywhere. To see what version you're running,
|
|
type:
|
|
perl -MHTML::Template -e 'print $HTML::Template::VERSION."\n"'
|
|
at a command prompt, or alternatively use the
|
|
sbin/testEnvironment.pl script included with WebGUI. If
|
|
you've had your WebGUI site running on versions prior to 6.4
|
|
then you should delete your lib/HTML folder as it contains
|
|
an outdated version of HTML::Template.
|
|
|
|
|
|
6.6.3
|
|
--------------------------------------------------------------------
|
|
* If you created your site using the create.sql script from 6.6.2
|
|
you will need to recreate it from the new create.sql script
|
|
from 6.6.3. The 6.6.2 version has some unrecoverable
|
|
problems in it. If you just upgraded to 6.6.2, you need not
|
|
worry, the upgrade is unaffected by this problem.
|
|
|
|
* If you're randomly getting logged out before upgrading to this
|
|
release, clear your browser cache and cookies after upgrading
|
|
to this release and the problem will go away.
|
|
|
|
|
|
6.6.0
|
|
--------------------------------------------------------------------
|
|
* Perl modules that used to be shipped with WebGUI are now required
|
|
to be installed on your system manually. You can optionally
|
|
just use the WebGUI runtime environment to save yourself
|
|
the hassle of downloading all of them. You can also install
|
|
them using testEnvironment.pl The new modules you'll need
|
|
to install are:
|
|
|
|
Log::Log4perl
|
|
Net::LDAP
|
|
Date::Manip
|
|
DBIx::FullTextSearch
|
|
HTML::Highlight
|
|
HTML::TagFilter
|
|
HTML::Template
|
|
Parse::PlainConfig
|
|
Tie::IxHash
|
|
Tie::CPHash
|
|
XML::RSSLite
|
|
XML::Simple
|
|
|
|
* After upgrading you'll need to create a log.conf file in your etc
|
|
folder for the new logger. For most situations you can just copy
|
|
log.conf.original to log.conf and you'll be fine. If you want
|
|
to set up custom logging rules, see this web page:
|
|
http://log4perl.sourceforge.net/releases/Log-Log4perl/docs/html/Log/Log4perl/Config.html
|
|
|
|
* The Payment plugins should provide two new methods: shippingCost and
|
|
shippingDescription. Plugins that do not have these methods
|
|
will fatal error when checking out.
|
|
|
|
* The Commerce/ConfirmCheckout template has a lot of new variables to
|
|
use, but also some (existing ones) have been renamed. Please refer
|
|
to the corresponding help file.
|
|
|
|
|
|
6.5.6
|
|
--------------------------------------------------------------------
|
|
* The uploadsAccessHandler.perl script has specific issues with
|
|
various versions of mod_perl and Perl CGI due to the many recent
|
|
changes in mod_perl and Perl CGI. For this reason it may not work
|
|
on your platform. We're working to make a script that will work
|
|
everywhere. Until then, using the latest versions of mod_perl and
|
|
Perl CGI should produce working results.
|
|
|
|
|
|
6.5.0
|
|
--------------------------------------------------------------------
|
|
* The International Macro must be enabled in all WebGUI configuration
|
|
files for the Help to work correctly.
|
|
|
|
6.4.0
|
|
--------------------------------------------------------------------
|
|
* Image Magick is no longer optional.
|
|
|
|
|
|
6.3.0
|
|
--------------------------------------------------------------------
|
|
* After upgrading your site you'll have to reset the privileges on
|
|
your uploads folder to make sure that the web server has
|
|
the privileges it needs to write due to a large number of
|
|
changes on the filesystem.
|
|
|
|
* In order to upgrade to 6.3.0 or beyond you need to have already
|
|
already upgraded to 6.2.0 or above. The upgrades will fail if
|
|
you try to jump from any 6.1 (or prior) version directly to
|
|
6.3.
|
|
|
|
* Your upgrade process will be a little different from here on out.
|
|
Use the following steps to do the upgrade:
|
|
|
|
a) Back up everything.
|
|
|
|
b) Extract the 6.3 archive over your existing install.
|
|
|
|
c) Restart apache (don't shut down as normal, just restart).
|
|
|
|
d) Run upgrade.pl in the sbin folder.
|
|
|
|
e) Test.
|
|
|
|
The reason for this is that WebGUI has an innovative new way
|
|
of releasing sites for public view as soon as they become
|
|
available during the upgrade, even while the other sites are
|
|
still being upgraded. Each site will have a maintenance
|
|
message displayed until its upgrade is complete.
|
|
|
|
* The EmptyTrash scheduler plugin has been removed since there's no
|
|
need for it with the more useful DeleteExpiredTrash module in
|
|
place.
|
|
|
|
* This upgrade process will run for a very long time and output a
|
|
lot of debug information which will be useful if something
|
|
goes wrong. You may wish to pipe the debug info to a log
|
|
file like this:
|
|
|
|
perl upgrade.pl --yourcommandlineoptions > /tmp/upgrade.log
|
|
|
|
* If you're using languages other than English, you'll need to get
|
|
new versions of those language files before upgrading. The
|
|
language file format has a new requirement. Also, the
|
|
language files are now all converted to UTF-8.
|
|
|
|
* If you were using any non-English language files on your site,
|
|
you may now have to convert your site content to UTF-8
|
|
format. Check with your language file provider for details.
|
|
|
|
* If you're upgrading from a release earlier than 5.5.0 then you'll
|
|
need to download and upgrade to 5.5.x before you can upgrade
|
|
to 6.3 or higher.
|
|
|
|
* All Site Map wobjects will be migrated to Navigation assets
|
|
during the upgrade. All the site map templates will
|
|
be lost. If you want them, save them before the upgrade. Also
|
|
check your site after the upgrade for all site maps to make
|
|
sure that they look the way you want them to look.
|
|
|
|
* All File Manager wobjects have been migrated to File Folder Layout
|
|
assets. The File Manager templates will be deleted during the
|
|
upgrade, so if you want to keep yours, get them before upgrading.
|
|
|
|
* If you have any SQL reports querying internal WebGUI database tables,
|
|
you'll need to update them after the upgrade. Most of WebGUI's
|
|
database tables will be changed during the upgrade process.
|
|
|
|
* If you have any custom page templates, they'll need to be updated
|
|
to work with the new Layout system. The templates have been
|
|
changed significantly enough that automatic migration of them is
|
|
not possible.
|
|
|
|
* You may add optional protection for your uploaded WebGUI files. This
|
|
will check the privileges of the files from the WebGUI database
|
|
before sending them to the browser. To enable this you must use
|
|
these directives:
|
|
|
|
PerlSetVar WebguiRoot /data/WebGUI
|
|
PerlRequire /data/WebGUI/sbin/uploadsAccessHandler.perl
|
|
|
|
And then add this to each virtual host you wish to protect:
|
|
|
|
PerlSetVar WebguiConfig www.example.com.conf
|
|
<Location /uploads>
|
|
PerlAccessHandler WebGUI::UploadsAccessHandler
|
|
</Location>
|
|
|
|
* If you have any custom code, please check out docs/migration.txt as
|
|
there have been many changes to the API in this release.
|
|
|
|
* There are many new components in this release, and as a result many
|
|
tables. Here is a list of the new tables. Make sure you have no
|
|
plug-ins installed that conflict with this, or tables you've
|
|
created for your own uses: Collaboration, Post, Thread,
|
|
Post_rating, Post_read, Folder, FileAsset, ITransact_recurringStatus,
|
|
ImageAsset, Layout, Shortcut, asset, assetHistory, commerceSettings,
|
|
redirect, shoppingCart, snippet, subscription, subscriptionCode,
|
|
subscriptionCodeBatch, subscriptionCodeSubscriptions, transaction,
|
|
transactionItem
|
|
|
|
* Due to the sweeping changes in this release the migration script may not
|
|
work perfectly on your site. It should get you 90% of the way there,
|
|
but it will be up to you to fix the problems it can't catch. Some of
|
|
the things to look out for are Collaboration System (formerly USS
|
|
and forum) templates. Also look at images and navigations as they've
|
|
been moved from outside the content system, to inside it as assets
|
|
in the new asset tree.
|
|
|
|
* If you are using the SMB auth module, please note that it has been removed
|
|
from this release. It has been long deprecated and is no longer an
|
|
official part of WebGUI. It will be made available in the user
|
|
contribs section of plainblack.com for people wishing to continue to
|
|
use/maintain it.
|
|
|
|
|
|
6.2.10
|
|
--------------------------------------------------------------------
|
|
* The recommended default location for the WebGUI log is now
|
|
/var/log/webgui.log instead of /data/webgui.log
|
|
|
|
* The default path for WebGUI backups is now /tmp/backups rather than
|
|
/data/backups
|
|
|
|
|
|
6.2.8
|
|
--------------------------------------------------------------------
|
|
* Due to a bug in the theme system, if you created any themes in any
|
|
6.2.x version prior to 6.2.8 they will need to be deleted and
|
|
recreated. Otherwise they will export a corrupt theme file.
|
|
|
|
|
|
6.2.2
|
|
--------------------------------------------------------------------
|
|
* If you used 6.1.1 for a while, and feel like there's something
|
|
wrong with your navigation or page tree, then there just
|
|
might be. We corrected a rather large problem in the Page
|
|
system that could have caused page tree corruption. To test
|
|
and fix this problem, get the page tree tools from the user
|
|
contribs area of plainblack.com. Be sure to back up your
|
|
databases before using this tool.
|
|
|
|
|
|
6.2.0
|
|
--------------------------------------------------------------------
|
|
* WebGUI now requires Time::HiRes to operate. Be sure to have it
|
|
installed prior to upgrading or the the upgrade will fail.
|
|
|
|
* Parts of the WebGUI API have changed once again, so be sure that
|
|
any third-party plug-ins you have installed have been updated
|
|
to work with 6.2 before upgrading.
|
|
|
|
* A new configuration option has been introduced:
|
|
exportPath = /path/to/export/dir
|
|
If exportPath is defined in the WebGUI config file, a new
|
|
"Export" icon will appear in the page toolbar.
|
|
|
|
|
|
6.1.0
|
|
--------------------------------------------------------------------
|
|
* See docs/migration.txt for changes in plug-in coding.
|
|
|
|
* You no longer need Data::Serializer.
|
|
|
|
* See docs/migration.txt for changes in the template system.
|
|
|
|
* See docs/migration.txt for changes in the Internationalization
|
|
and help systems.
|
|
|
|
* If you're using any third-party plug-ins, you'll need to get
|
|
updated versions to work with 6.1.
|
|
|
|
* If you're using a language other than English on your current site,
|
|
you'll need to obtain a language pack from either the user
|
|
contributions or one of the WebGUI Worldwide sites.
|
|
|
|
* Each user's language has been reset to the default language for
|
|
the site as specified in the profile settings.
|
|
|
|
* We removed a bunch of the cryptic-hack code that was allowing
|
|
backward compatibility all the way back to some 2.x, 3.x, and
|
|
4.x stuff. To be sure that your site will still work, copy
|
|
the gateway script (index.pl) over your old one. Also make
|
|
sure you have extrasPath and extrasURL defined in your config
|
|
file.
|
|
|
|
* The ThumbnailLinker macro has been removed. You can now use the
|
|
Thumbnail macro because it is templated.
|
|
|
|
|
|
6.0.2
|
|
--------------------------------------------------------------------
|
|
* You need to add all of your site aliases to the sitename variable
|
|
in your WebGUI config file.
|
|
|
|
|
|
6.0.1
|
|
--------------------------------------------------------------------
|
|
* Apache 2.0 is now the recommended web server for WebGUI. As such
|
|
sbin/preload.perl has been defaulted for use with mod_perl
|
|
2.0. If you are still using Apache 1.3, don't worry, WebGUI
|
|
will still work great for you. You just need to edit
|
|
sbin/preload.perl to match your environment.
|
|
|
|
|
|
6.0.0
|
|
--------------------------------------------------------------------
|
|
* As part of the upgrade process our scripts will attempt to
|
|
migrate your styles, page, FAQ, Item, Link List, and
|
|
SQL Report templates. However, the migration scripts are not
|
|
perfect due to the wide-variety of templates out there, so
|
|
you may need to update some portions of your templates
|
|
manually.
|
|
|
|
* The Authentication Module API has been completely rewritten.
|
|
Please see docs/migration.txt for details.
|
|
|
|
* The Paginator API has been significantly changed.
|
|
Please see docs/migration.txt for details.
|
|
|
|
* WebGUI now requires the following Perl modules to be installed:
|
|
Data::Serializer
|
|
SOAP::Lite
|
|
Cache::Cache (no longer optional)
|
|
|
|
WARNING: Be sure you install these modules BEFORE you attempt to
|
|
upgrade or the upgrade will fail and you'll have a mess to
|
|
clean up!
|
|
|
|
* If you've created any custom Events Calendar templates, they will
|
|
no longer work due to the new template structure for events
|
|
calendars. Your old templates will remain intact, however,
|
|
so that you can migrate them manually to the new template
|
|
variables.
|
|
|
|
* The Synopsis macro no longer exists. If you were using it to
|
|
retrieve the current page's synopsis, then please use the
|
|
^Page("synopsis"); macro. If you were using it to build a
|
|
synopsis style navigation please use the new ^Navigation();
|
|
macro.
|
|
|
|
* The old navigation system has been entirely replaced. If you've
|
|
built or are using any navigation components that did not
|
|
come with WebGUI then you'll need to remove them and use
|
|
the new configurable navigation system. See migration.txt
|
|
for additional details.
|
|
|
|
* The old realtime search subsystem has been replaced with the new
|
|
indexed search wobject. As such, we've removed the ^?; macro.
|
|
If you were using the ^?; macro then you'll need to set up
|
|
a search wobject to replace it.
|
|
|
|
* Themes that were created with 5.x versions of WebGUI will fail to
|
|
import into WebGUI 6.0. Sometime after the release of 6.0
|
|
(gamma) there will be a theme converter available on
|
|
plainblack.com to convert your old 5.x themes into 6.0
|
|
themes. If you've already imported a 5.x theme you have
|
|
nothing to worry about. All of the theme components will
|
|
automatically be converted to 6.0.
|
|
|
|
* If you have any SQL Reports going against any USS, they will need
|
|
to be updated as the USS tables have changed.
|
|
|
|
* During the upgrade process you may see some database errors during
|
|
the migration of SQL Reports. Don't be alarmed. Your upgrade
|
|
has not failed. Instead, some of the queries in the SQL Reports
|
|
may have failed and will cause the SQL Report templates to not
|
|
be automatically generated.
|
|
|
|
|