root/1.8.3/branches/experimental/UPGRADING

============================================================================
                         Upgrading to PennMUSH 1.8.x
============================================================================

This file explains how to upgrade to a new version of PennMUSH.

There are three basic upgrade situations:
  A. You're running a stock ("vanilla") PennMUSH server of some
     version and you want to upgrade to a later version
  B. You've hacked your server source code a little bit here and there
     (adding a flag, for example). Hacks to the *local.c files don't
     count as hacks, as they're easy to handle.
  C. You've hacked your server source code a lot.

There is also a list of upgrade "GOTCHAS" at the end of this file.
Please read them.

The PennMUSH developers actually only support situation A, but we'll
give some useful tips for B and C here, too.

DISCLAIMER: It is very wise to always back up your current working
MUSH directories before you try an upgrade. You were warned.

============================================================================

A. Vanilla upgrade

You have basically two choices here: upgrade with patch files, or
build a whole new distribution.

A.1. Upgrading with patch files

This is the easiest way to upgrade your source code if you're keeping
up with patches as they come out, or if you're upgrading patchlevels
within a release (e.g., within 1.8.0).

To upgrade with patch files, get all the patch files for higher
patchlevels than your current version. For example, if you're running
1.8.0p0 and the latest version is 1.8.0p4, you need patches 1-4.

These files are stored at http://ftp.pennmush.org/Source and usually
named things like 1.8.0-patch02 (the patch from 1.8.0p1 to 1.8.0p2)
or, in some cases, 1.7.6p16-1.8.0p0.patch (the patch from 1.7.6p16 to
1.8.0p0).

Each patch file contains instructions at the top explaining how to
apply it. FOLLOW THESE! Don't assume they're all the same. The options
to use with the patch program change, and sometimes further steps are
required.

After you've applied all the patches and followed all the
instructions, you should be good to go. In most cases, you can simply
@shutdown/reboot after the final successful compile. If
@shutdown/reboot crashes, you'll have to restart again.

A.2. Building a new distribution

When you're upgrading across release and no patchlevel is provided to
make the upgrade (e.g. from 1.7.4p3 to 1.8.0p0), it's often easier to
simply build a new distribution following the INSTALL instructions,
but with your old configuration stuff.

Move your older version of PennMUSH in a directory called oldpenn/,
unpack the new one (it will unpack into pennmush/).

All of the steps below should be taken before running Configure for
the new version:

A.2.a. options.h and game/*.cnf

You can copy the options.h file and game/mush.cnf file from your old
version to the new version. The 'make update' command (run after
Configure) will compare your files with the newly distributed ones and
tell you about options that have been added or removed. If you have
any options defined that the new version doesn't recognize, you'll be
asked if you want to retain them (which is safe).

If your mush.cnf file is called something else, copy it to mush.cnf in
pennmush/game anyway, since that's the file that gets updated. Then
make a link to that file called whatever.cnf if you want to use that.

If you've modified the restart script, you'll have to decide if your
modified script is still appropriate, or modify a copy of the
distributed game/restart script as you like it. it is highly
recommended that you copy restart to a second file, called something
like restart.local, and modify and use it instead of the stock restart
script to reduce conflicts when patching.

You can also copy your old game/access.cnf, game/sitelock.cnf, and
game/txt/*.txt files into the appropriate locations. You may wish to
do the same thing for game/restrict.cnf, but you should compare it to
the new version, as restrictions that may formerly have been compiled
into the server may now be specified in restrict.cnf instead.

A.2.b. src/*local.c

You should copy local.c, cmdlocal.c, and funlocal.c from oldpenn/src
to pennmush/src if you want to retain this local code. Of course, it
may not still work, but it's quite likely that it will. If you don't
have any such code, you can skip this step.

A.2.c. Databases

This MUSH version should read databases along the main branch of MUSH
evolution -- TinyMUD, vanilla TinyMUSH up to 2.0, MicroMUSH, and all
Pern/PennMUSH versions. If you need to convert a TinyMUSH 2.0
database, please contact Amberyl, and she'll mail you an extension to
2.0 that will dump a 1.50-readable flatfile. You're probably out of
luck with databases for TinyMUSH 2.2 and later.

Be sure that your options.h settings correctly reflect the type of
password encryption that was used on your database. The default has
changed to SHS, so if your db used crypt(3) encryption, be sure you
set the appropriate definition in options.h.

*** If you are upgrading from 1.7.4 (or earlier) to 1.7.7 (or later),
*** you must first load your old database under PennMUSH 1.7.6 and
*** then dump it, and load this converted database under your
*** target version of PennMUSH. PennMUSH 1.7.7+ can no longer read
*** 1.7.4 databases.

============================================================================

B. PennMUSH with a few hacks

When you have only a few local hacks outside of the src/*local.c
files, you can often patch up using the patch file method discussed
above. Alternatively, you can build a new version and reapply your
changes.

One small exception is upgrading from a version that used the old flag
system to one that uses the new flag system (post-1.7.7p5), if you've
added flags or toggles.  You probably had an #define in hdrs/flags.h
for your flag's bit value.  This now should be moved to
hdrs/oldflags.h; you should leave in the table entry in
src/flags.c. If you set up a macro for testing your flag in
hdrs/mushdb.h, you'll need to change it to use the has_flag_by_name()
function - see the many examples in that file.

If this isn't suitable (you're crossing releases or your hacks are too
many for this to work cleanly), see below.

============================================================================

C. PennMUSH with a lot of hacks

If you've seriously hacked your server source code, you're on your own
in terms of keeping up with new patchlevels. Some people apply
patchfiles and fix the rejected hunks.

A better approach is probably that described in the Guide for Gods,
and involves creating a set of patches from the distributed old
version of pennmush (e.g. 1.7.4p16) to your hacked version of pennmush
(e.g. 1.7.4p16 with hacks), and then applying those patches to the new
version of PennMUSH (e.g. 1.8.0p0) to create a hacked version
thereof. If some patch hunks fail, you'll have to apply them manually.

Probably the best approach is to keep all multiple versions of the
code (old distributed, old hacked, new distributed, new hacked) under
a source code control system like prcs that can merge changes between
versions. See the Guide for Gods.

============================================================================

IMPORTANT NOTES FOR THOSE UPGRADING TO 1.8.0 FROM 1.7.6:

* Softcode gotchas:

  * Wizards (other than God) and royalty are no longer treated as No_Pay
    unless the No_Pay power is explicitly set on them, although they
    can still give (themselves or others) as many pennies as they wish.
    This helps stop runaway wizards in the queue (they'll run out of cash
    like anyone else). To get the old behavior back, @power your admin
    No_Pay. You probably want to @power any globals that use search(),
    children(), mail*stats(), etc, No_Pay as well. 
  * @desc can no longer be gotten remotely without privileges.
    @desc on privileged objects can now be evaluated by mortals.
  * @adisconnect is triggered on every disconnection, partial or full.
    This mirrors the behavior of @aconnect. Use %1 (the number of
    remaining connections) to distinguish between partial and full
    disconnects in @adisconnect code.
  * Players can no longer be set CHOWN_OK.  If you have existing CHOWN_OK
    players, you probably want to unset this from them, or the results
    will be confusing (they'll continue to appear to have the flag,
    even though it won't be testable or settable or clearable; this is
    desired behavior).
  * New HEAVY admin flag, prevents an object from being teleported
    by a mortal between two containers they own. Admin without this
    flag CAN be teleported.

* Hardcode/db/startup gotchas:
  * After each @startup is enqueued (during startup or @restart/all),
    we immediately run up to 5 queue cycles. This allows, e.g., God's
    @startup to up to five levels of @dol/@tr/@switch/etc and still have
    the queued code run ahead of other startups. This requires that you
    keep God's dbref as #1. 
  * netmush is now started with only a single argument - the path to
    the configuration file. The error log file (typically game/netmush.log
    is now configured in mush.cnf. 
  * CHAT_SYSTEM option removed. If you don't want to use the chat system,
    use restrict.cnf to disable @channel, @chat, etc.
  * USE_MAILER and MAIL_ALIAS options removed. If you don't want to 
    use the @mail or @malias systems, use restrict.cnf to disable
    the associated commands.
  * QUOTA, EMPTY_ATTRS, and FUNCTION_SIDE_EFFECTS options are now 
    runtime options, instead of compile-time.
  * SINGLE_LOGFILE option removed, and log filenames are now 
    runtime options. You may now give the same name to multiple log
    files and get a more fine-grained version of the same effect.
  * src/Makefile is now autobuilt from src/Makefile.SH. IF you use
    local hacks that require src/Makefile, this is likely to be a problem
    for you. You'll want to start patching Makefile.SH instead.
  * The new code can no longer read databases created by versions of Penn
    before 1.7.5p0. If you need to do this, load it in 1.7.6, shutdown,
    and use that database.
  * PROFILING #define for use when profiling the code (surprise). This
    just disables the CPU timer.
  * help-like commands without arguments now use the command name
    as the argument. E.g. 'news' now looks for topic 'news', instead of
    'help'. If not found, we fall back on help.
  * Mail messages now track not only the dbref of the sender but the
    sender's creation time, so messages from dbrefs that have been
    nuked and recreated can be distinguished from messages from the
    original sender. This modifies the maildb and make it not usable
    with older versions. All existing @mail is grandfathered in, and
    can't be tracked this way.