cmlenz@39: Upgrade Instructions
cmlenz@39: ====================
cmlenz@39: 
cmlenz@39: A Trac environment sometimes needs to be upgraded before it can be used with
cmlenz@39: a new version of Trac. This document describes the steps necessary to upgrade
cmlenz@39: an environment.
cmlenz@39: 
cmlenz@39: Note that Environment upgrades are not necessary for minor version releases
cmlenz@39: unless otherwise noted. For example, there's no need to upgrade a Trac
cmlenz@39: environment created with (or upgraded) 0.8.0 when installing 0.8.4 (or any
cmlenz@39: other 0.8.x release).
cmlenz@39: 
cmlenz@39: General Instructions
cmlenz@39: --------------------
cmlenz@39: Typically, there are four steps involved in upgrading to a newer version of
cmlenz@39: Trac:
cmlenz@39: 
cmlenz@39: 1. Update the Trac Code
cmlenz@39: 
cmlenz@39: Get the new version of Trac, either by downloading an offical release package
cmlenz@39: or by checking it out from the Subversion repository.
cmlenz@39: 
cmlenz@39: If you have a source distribution, you need to run
cmlenz@39: 
cmlenz@39:    python setup.py install
cmlenz@39: 
cmlenz@39: to install the new version. If you've downloaded the Windows installer, you
cmlenz@39: execute it, and so on.
cmlenz@39: 
cmlenz@39: In any case, if you're doing a major version upgrade (such as from 0.8 to
cmlenz@39: 0.9), it is highly recommended that you first remove the existing Trac code.
cmlenz@39: To do this, you need to delete the `trac` directory from the Python
cmlenz@39: `lib/site-packages` directory. You may also want to remove the Trac `cgi-bin`,
cmlenz@39: `htdocs` and `templates` directories that are commonly found in a directory
cmlenz@39: called `share/trac` (the exact location depends on your platform).
cmlenz@39: 
cmlenz@39: 2. Upgrade the Trac Environment
cmlenz@39: 
cmlenz@39: Unless noted otherwise, upgrading between major versions (such as 0.8 and
cmlenz@39: 0.9) involves changes to the database schema, and possibly the layout of the
cmlenz@39: environment. Fortunately, Trac provides automated upgrade scripts to ease the
cmlenz@39: pain. These scripts are run via `trac-admin`:
cmlenz@39: 
cmlenz@39:    trac-admin /path/to/projenv upgrade
cmlenz@39: 
cmlenz@39: This command will do nothing if the environment is already up-to-date.
cmlenz@39: 
cmlenz@39: 3. Update the Trac Documentation
cmlenz@39: 
cmlenz@39: Every Trac environment includes a copy of the Trac documentation for the
cmlenz@39: installed version. As you probably want to keep the included documentation in
cmlenz@39: sync with the installed version of Trac, `trac-admin` provides a command to
cmlenz@39: upgrade the documentation:
cmlenz@39: 
cmlenz@39:    trac-admin /path/to/projenv wiki upgrade
cmlenz@39: 
cmlenz@39: Note that this procedure will of course leave your `WikiStart` page intact.
cmlenz@39: 
cmlenz@39: 4. Restart the Web Server
cmlenz@39: 
cmlenz@39: In order to reload the new Trac code you will need to restart your web
cmlenz@39: server (note this is not necessary for CGI).
cmlenz@39: 
cmlenz@39: 
cmlenz@39: The following sections discuss any extra actions that may need to be taken
cmlenz@39: to upgrade to specific versions of Trac.
cmlenz@39: 
cmlenz@39: 
cmlenz@39: From 0.9-beta to 0.9
cmlenz@39: --------------------
cmlenz@39: 
cmlenz@39: If inclusion of the static resources (style sheets, javascript, images) is not
cmlenz@39: working, check the value of the `htdocs_location` in trac.ini. For mod_python,
cmlenz@39: Tracd and FastCGI, you can simply remove the option altogether. For CGI, you
cmlenz@39: should fix it to point to the URL you mapped the Trac `htdocs` directory to.
cmlenz@39: 
cmlenz@39: If you've been using plugins with a beta release of Trac 0.9, or have 
cmlenz@39: disabled some of the built-in components, you might have to update the rules
cmlenz@39: for disabling/enabling components in trac.ini. In particular, globally 
cmlenz@39: installed plugins now need to be enabled explicitly. See the TracPlugins and 
cmlenz@39: TracIni wiki pages for more information.
cmlenz@39: 
cmlenz@39: If you want to enable the display of all ticket changes in the timeline (the
cmlenz@39: Ticket Details option), you now have to explicitly enable that in trac.ini,
cmlenz@39: too:
cmlenz@39: 
cmlenz@39:    [timeline]
cmlenz@39:    ticket_show_details = true
cmlenz@39: 
cmlenz@39: 
cmlenz@39: From 0.8.x to 0.9
cmlenz@39: -----------------
cmlenz@39: 
cmlenz@39: mod_python users will need to change the name of the mod_python handler in
cmlenz@39: the Apache HTTPD configuration:
cmlenz@39: 
cmlenz@39:    from: PythonHandler trac.ModPythonHandler
cmlenz@39:    to:   PythonHandler trac.web.modpython_frontend
cmlenz@39: 
cmlenz@39: If you have PySQLite 2.x installed, Trac will now try to open your SQLite
cmlenz@39: database using the SQLite 3.x file format. The database formats used by
cmlenz@39: SQLite 2.8.x and SQLite 3.x are incompatible. If you get an error like "file
cmlenz@39: is encrypted or is not a database" after upgrading, then you must convert
cmlenz@39: your database file.
cmlenz@39: 
cmlenz@39: To do this, you need to have both SQLite 2.8.x and SQLite 3.x installed (they
cmlenz@39: have different filenames so can coexist on the same system). Then use the
cmlenz@39: following commands:
cmlenz@39: 
cmlenz@39:    mv trac.db trac2.db
cmlenz@39:    sqlite trac2.db .dump | sqlite3 trac.db
cmlenz@39: 
cmlenz@39: After testing that the conversion was successful, the `trac2.db` file can be
cmlenz@39: deleted. For more information on the SQLite upgrade see
cmlenz@39: http://www.sqlite.org/version3.html.
cmlenz@39: 
cmlenz@39: 
cmlenz@39: From 0.7.x to 0.8
cmlenz@39: -----------------
cmlenz@39: 
cmlenz@39: 0.8 adds a new roadmap feature which requires additional permissions. While a
cmlenz@39: fresh installation will by default grant `ROADMAP_VIEW` and `MILESTONE_VIEW`
cmlenz@39: permissions to anonymous, these permissions have to be granted manually when
cmlenz@39: upgrading:
cmlenz@39: 
cmlenz@39:    trac-admin /path/to/projectenv permission add anonymous MILESTONE_VIEW
cmlenz@39:    trac-admin /path/to/projectenv permission add anonymous ROADMAP_VIEW
cmlenz@39: 
cmlenz@39: 
cmlenz@39: From 0.6.x to 0.7
cmlenz@39: -----------------
cmlenz@39: Trac 0.7 introduced a new database format, requiring manual upgrade.
cmlenz@39: 
cmlenz@39: Previous versions of Trac stored wiki pages, ticket, reports, settings,
cmlenz@39: etc. in a single SQLite database file. Trac 0.7 replaces this file
cmlenz@39: with a new backend storage format; the 'Trac Environment', which is a
cmlenz@39: directory containing an SQLite database, a human-readable configuration file,
cmlenz@39: log-files and attachments.
cmlenz@39: 
cmlenz@39: Fear not though, old-style Trac databases can easily be converted to
cmlenz@39: Environments using the included `tracdb2env` program as follows:
cmlenz@39: 
cmlenz@39:    tracdb2env /path/to/old/project.db /path/to/new/projectenv
cmlenz@39: 
cmlenz@39: `tracdb2env` will create a new environment and copy the information from the
cmlenz@39: old database to the new environment. The existing database will not be
cmlenz@39: modified.
cmlenz@39: 
cmlenz@39: You also need to update your apache configuration:
cmlenz@39: 
cmlenz@39: Change the line:
cmlenz@39: 
cmlenz@39:    SetEnv TRAC_DB "/path/to/old/project.db"
cmlenz@39: 
cmlenz@39: to:
cmlenz@39: 
cmlenz@39:    SetEnv TRAC_ENV "/path/to/new/projectenv"
cmlenz@39: 
cmlenz@39: 
cmlenz@39: ----
cmlenz@39: 
cmlenz@39: If you have trouble upgrading Trac, please ask questions on the mailing list:
cmlenz@39: 
cmlenz@39:   <http://projects.edgewall.com/trac/wiki/MailingList>
cmlenz@39: 
cmlenz@39: Or for other support options, see:
cmlenz@39: 
cmlenz@39:   <http://projects.edgewall.com/trac/wiki/TracSupport>