Mercurial > genshi > mirror
comparison examples/trac/UPGRADE @ 39:93b4dcbafd7b trunk
Copy Trac to main branch.
| author | cmlenz |
|---|---|
| date | Mon, 03 Jul 2006 18:53:27 +0000 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 38:ee669cb9cccc | 39:93b4dcbafd7b |
|---|---|
| 1 Upgrade Instructions | |
| 2 ==================== | |
| 3 | |
| 4 A Trac environment sometimes needs to be upgraded before it can be used with | |
| 5 a new version of Trac. This document describes the steps necessary to upgrade | |
| 6 an environment. | |
| 7 | |
| 8 Note that Environment upgrades are not necessary for minor version releases | |
| 9 unless otherwise noted. For example, there's no need to upgrade a Trac | |
| 10 environment created with (or upgraded) 0.8.0 when installing 0.8.4 (or any | |
| 11 other 0.8.x release). | |
| 12 | |
| 13 General Instructions | |
| 14 -------------------- | |
| 15 Typically, there are four steps involved in upgrading to a newer version of | |
| 16 Trac: | |
| 17 | |
| 18 1. Update the Trac Code | |
| 19 | |
| 20 Get the new version of Trac, either by downloading an offical release package | |
| 21 or by checking it out from the Subversion repository. | |
| 22 | |
| 23 If you have a source distribution, you need to run | |
| 24 | |
| 25 python setup.py install | |
| 26 | |
| 27 to install the new version. If you've downloaded the Windows installer, you | |
| 28 execute it, and so on. | |
| 29 | |
| 30 In any case, if you're doing a major version upgrade (such as from 0.8 to | |
| 31 0.9), it is highly recommended that you first remove the existing Trac code. | |
| 32 To do this, you need to delete the `trac` directory from the Python | |
| 33 `lib/site-packages` directory. You may also want to remove the Trac `cgi-bin`, | |
| 34 `htdocs` and `templates` directories that are commonly found in a directory | |
| 35 called `share/trac` (the exact location depends on your platform). | |
| 36 | |
| 37 2. Upgrade the Trac Environment | |
| 38 | |
| 39 Unless noted otherwise, upgrading between major versions (such as 0.8 and | |
| 40 0.9) involves changes to the database schema, and possibly the layout of the | |
| 41 environment. Fortunately, Trac provides automated upgrade scripts to ease the | |
| 42 pain. These scripts are run via `trac-admin`: | |
| 43 | |
| 44 trac-admin /path/to/projenv upgrade | |
| 45 | |
| 46 This command will do nothing if the environment is already up-to-date. | |
| 47 | |
| 48 3. Update the Trac Documentation | |
| 49 | |
| 50 Every Trac environment includes a copy of the Trac documentation for the | |
| 51 installed version. As you probably want to keep the included documentation in | |
| 52 sync with the installed version of Trac, `trac-admin` provides a command to | |
| 53 upgrade the documentation: | |
| 54 | |
| 55 trac-admin /path/to/projenv wiki upgrade | |
| 56 | |
| 57 Note that this procedure will of course leave your `WikiStart` page intact. | |
| 58 | |
| 59 4. Restart the Web Server | |
| 60 | |
| 61 In order to reload the new Trac code you will need to restart your web | |
| 62 server (note this is not necessary for CGI). | |
| 63 | |
| 64 | |
| 65 The following sections discuss any extra actions that may need to be taken | |
| 66 to upgrade to specific versions of Trac. | |
| 67 | |
| 68 | |
| 69 From 0.9-beta to 0.9 | |
| 70 -------------------- | |
| 71 | |
| 72 If inclusion of the static resources (style sheets, javascript, images) is not | |
| 73 working, check the value of the `htdocs_location` in trac.ini. For mod_python, | |
| 74 Tracd and FastCGI, you can simply remove the option altogether. For CGI, you | |
| 75 should fix it to point to the URL you mapped the Trac `htdocs` directory to. | |
| 76 | |
| 77 If you've been using plugins with a beta release of Trac 0.9, or have | |
| 78 disabled some of the built-in components, you might have to update the rules | |
| 79 for disabling/enabling components in trac.ini. In particular, globally | |
| 80 installed plugins now need to be enabled explicitly. See the TracPlugins and | |
| 81 TracIni wiki pages for more information. | |
| 82 | |
| 83 If you want to enable the display of all ticket changes in the timeline (the | |
| 84 Ticket Details option), you now have to explicitly enable that in trac.ini, | |
| 85 too: | |
| 86 | |
| 87 [timeline] | |
| 88 ticket_show_details = true | |
| 89 | |
| 90 | |
| 91 From 0.8.x to 0.9 | |
| 92 ----------------- | |
| 93 | |
| 94 mod_python users will need to change the name of the mod_python handler in | |
| 95 the Apache HTTPD configuration: | |
| 96 | |
| 97 from: PythonHandler trac.ModPythonHandler | |
| 98 to: PythonHandler trac.web.modpython_frontend | |
| 99 | |
| 100 If you have PySQLite 2.x installed, Trac will now try to open your SQLite | |
| 101 database using the SQLite 3.x file format. The database formats used by | |
| 102 SQLite 2.8.x and SQLite 3.x are incompatible. If you get an error like "file | |
| 103 is encrypted or is not a database" after upgrading, then you must convert | |
| 104 your database file. | |
| 105 | |
| 106 To do this, you need to have both SQLite 2.8.x and SQLite 3.x installed (they | |
| 107 have different filenames so can coexist on the same system). Then use the | |
| 108 following commands: | |
| 109 | |
| 110 mv trac.db trac2.db | |
| 111 sqlite trac2.db .dump | sqlite3 trac.db | |
| 112 | |
| 113 After testing that the conversion was successful, the `trac2.db` file can be | |
| 114 deleted. For more information on the SQLite upgrade see | |
| 115 http://www.sqlite.org/version3.html. | |
| 116 | |
| 117 | |
| 118 From 0.7.x to 0.8 | |
| 119 ----------------- | |
| 120 | |
| 121 0.8 adds a new roadmap feature which requires additional permissions. While a | |
| 122 fresh installation will by default grant `ROADMAP_VIEW` and `MILESTONE_VIEW` | |
| 123 permissions to anonymous, these permissions have to be granted manually when | |
| 124 upgrading: | |
| 125 | |
| 126 trac-admin /path/to/projectenv permission add anonymous MILESTONE_VIEW | |
| 127 trac-admin /path/to/projectenv permission add anonymous ROADMAP_VIEW | |
| 128 | |
| 129 | |
| 130 From 0.6.x to 0.7 | |
| 131 ----------------- | |
| 132 Trac 0.7 introduced a new database format, requiring manual upgrade. | |
| 133 | |
| 134 Previous versions of Trac stored wiki pages, ticket, reports, settings, | |
| 135 etc. in a single SQLite database file. Trac 0.7 replaces this file | |
| 136 with a new backend storage format; the 'Trac Environment', which is a | |
| 137 directory containing an SQLite database, a human-readable configuration file, | |
| 138 log-files and attachments. | |
| 139 | |
| 140 Fear not though, old-style Trac databases can easily be converted to | |
| 141 Environments using the included `tracdb2env` program as follows: | |
| 142 | |
| 143 tracdb2env /path/to/old/project.db /path/to/new/projectenv | |
| 144 | |
| 145 `tracdb2env` will create a new environment and copy the information from the | |
| 146 old database to the new environment. The existing database will not be | |
| 147 modified. | |
| 148 | |
| 149 You also need to update your apache configuration: | |
| 150 | |
| 151 Change the line: | |
| 152 | |
| 153 SetEnv TRAC_DB "/path/to/old/project.db" | |
| 154 | |
| 155 to: | |
| 156 | |
| 157 SetEnv TRAC_ENV "/path/to/new/projectenv" | |
| 158 | |
| 159 | |
| 160 ---- | |
| 161 | |
| 162 If you have trouble upgrading Trac, please ask questions on the mailing list: | |
| 163 | |
| 164 <http://projects.edgewall.com/trac/wiki/MailingList> | |
| 165 | |
| 166 Or for other support options, see: | |
| 167 | |
| 168 <http://projects.edgewall.com/trac/wiki/TracSupport> |