= Trac FAQ Here you can find answers to some frequently asked questions about Trac. If you have a question not answered on this page, you can ask it on the MailingList or in the IrcChannel. See the TracSupport page for more options on getting support for Trac. **Note:** If you don't find the answer you are looking for here and you are using Trac 0.12 or older versions, also have a look in [wiki:"0.12/TracFaq"]. ---- [[PageOutline(2-6,,inline)]] ---- == What is Trac and how can it help me? [wikipedia:Trac] is an open-source, web-based project management and bug tracking system. A list of key features can be found on TracFeatures. {{{#!comment Maybe directly from [http://www.edgewall.com/trac/ Edgewall]. Sounds like we need a TracFeatures page. Just as a first cut at an outline: - Project description - open source - Integrated Wiki - Version control support (primary is Subversion, but now others) - Milestones and Roadmap - Ticketing - Reporting (custom and fixed complex ones) - Tight integration for cross links between different types of data - Extensible (see custom ticket fields, plugins, macros) }}} == Installation troubleshooting === Installation from source ==== Q: Why do I get `NameError: global name 'log' is not defined` when trying to use `setup.py`? {{{#!sh ../trunk/$ python setup.py egg_info running egg_info ... File "build/bdist.linux-x86_64/egg/setuptools/svn_util.py", line 55, in get_sections NameError: global name 'log' is not defined }}} **A:** You're most likely working from a Subversion **1.7** checkout and you're using a too old `setuptools` package, eg `/setuptools-0.7a1dev_r66608`. Upgrade to a newer setuptools, downgrade to svn 1.6.x, or use distribute. See also #7598. ==== Q: Why does installing `distribute` fail with `ValueError: A 0.7-series setuptools cannot be installed with distribute.`? You tried to install `distribute` as advised elsewhere: {{{#!sh $ curl http://python-distribute.org/distribute_setup.py | python }}} but you're greeted with: {{{#!sh ValueError: A 0.7-series setuptools cannot be installed with distribute. Found one at /packages/trac/virtualenv-0.13/lib/python2.7/site-packages/setuptools-0.7a1dev_r66608-py2.7.egg }}} **A:** This is `setuptools` giving you a last fight. You can remove the offending setuptools .egg and if it keeps re-appearing, you have it installed not only in the virtualenv but also in the parent Python installation, the one in which you installed virtualenv itself. If this is the case, remove it from there as well and installing distribute should now work. ==== Q: Why does Apache crash (500) with a `ZipImportError` in the error log? {{{ [Tue Aug 07 09:08:26 2012] [error] [client 172.25.16.59] mod_wsgi (pid=16444): Exception occurred processing WSGI script '/packages/trac/virtualenv-0.13/bin/trac.wsgi'., referer: http://dserver/trac/bct/timeline ... [Tue Aug 07 09:08:26 2012] [error] [client 172.25.16.59] File "build/bdist.linux-x86_64/egg/pkg_resources.py", line 1197, in _get, referer: xxx/trac/bct/timeline [Tue Aug 07 09:08:26 2012] [error] [client 172.25.16.59] ZipImportError: bad local file header in /packages/trac/virtualenv-0.13/lib/python2.7/site-packages/Genshi-0.6-py2.7.egg, referer: xxx/trac/bct/timeline }}} **A:** You probably forgot to stop and restart your server during an upgrade. The zip importer mechanism keeps an internal cache which has trouble detecting replaced files, so a restart is needed, see TracUpgrade#ZipImportError. ==== Q: Why do ticket notification emails contain unexpected backslash characters? You installed Trac from PyPI using `easy_install` or `pip`, along with Genshi 0.7. Your ticket notification emails have unexpected backslash characters (for an example, see #11572). **A:** This is the result of a defect in Genshi 0.7 (genshi:#569). Until Genshi 0.7.1 is released, your options are: * Use Trac 1.0.3 or later. The zip archive has been built on Linux rather than Windows since 1.0.3. * Downgrade to Genshi 0.6.1 * Convert the line endings of the ticket notification email template from `CRLF` to `LF`. For example, on a Unix-like system you can run the following from the directory in which the egg is installed: {{{#!sh $ dos2unix Trac-1.0.1-py2.7.egg/trac/ticket/templates/ticket_notify_email.txt }}} You may need elevated privileges, and your egg may have a different name depending on your Trac and Python versions. ==== Q: Why do I see `IndexError: pop from empty list` when trying to add an attachment? The issue is seen with Genshi 0.6.1 and 0.7 for languages other than English. The issue can be avoided by downgrading to Genshi 0.6 or upgrading to Genshi 0.7.1. From Trac 1.4 onwards, the Genshi templating engine has been replaced in favor of Jinja2, and this issue should not occur. === Upgrade troubleshooting ==== Q: Trac /about says 1.0, but the style looks pre-1.0 **A:** You probably just need to convince your browser that the CSS files have changed. Try force reloading by entering `CTRL+R` or `CTRL+Shift+R`, depending on your browser. This is a common issue, see #10797. If that still doesn't work, look in your server configuration to see where the chrome files are supposed to be served from (`Alias` or `AliasMatch` directive), and maybe you are serving them as static files from a different location: {{{#!apache Alias /trac/bct/chrome /packages/trac/virtualenv-0.13/share/htdocs }}} In this case, don't forget to: {{{#!sh $ trac-admin deploy /packages/trac/virtualenv-0.13/share }}} See TracUpgrade#a5.Refreshstaticresources. ==== Q: Attachments are missing after upgrade to Trac v1.0.1 **A:** Most likely the script `db28.py` failed, see #11370. Please report any additional information on the MailingList. If the attachments are not moved when upgrading your Trac instance, add the following code to `run-db28.py`: {{{#!python # -*- coding: utf-8 -*- # # Execute `do_upgrade` in trac/upgrades/db28.py # # Usage: python run-db28.py /path/to/tracenv # from __future__ import with_statement from trac.env import Environment from trac.upgrades import db28 def main(args): for arg in args: env = Environment(arg) with env.db_transaction as db: cursor = db.cursor() db28.do_upgrade(env, 28, cursor) if __name__ == '__main__': import sys main(sys.argv[1:]) }}} Then run the script against the broken environment: {{{#!sh $ python run-db28.py /path/to/tracenv }}} == Usage troubleshooting There is a separate page on [MostFrequentDuplicates Most Frequently Reported Bugs in Trac]. == Trac development === Q: How to extend Trac? **A:** There are two ways in which Trac's functionality is extended: 1. Functionality is added to Trac core, provided the features that the functionality offers is used often enough and has been tested extensively in the field. 1. A lower barrier to entry to add new functionality to Trac is to write a [TracPlugins plugin] in Python. The documentation in TracDev/ is the authoritative source, with the [TracDev#Overviews overview] pages as a good starting point. Plugins can be found in the following locations: 1. The community site [TracHacks:WikiStart trac-hacks.org] is the portal where upwards of 700 Trac plugins are hosted. 1. There is a [https://github.com/trac-hacks trac-hacks organization on GitHub]. 1. The !PyPi site contains a collection of [https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Trac Trac plugins]. === Q: How to contribute to Trac? **A:** There are many ways to contribute back, see HowToContribute for details. Also have a look at the documentation below TracDev/, in particular the pages below the [TracDev#Contributing Contributing] section.