文档搜索 > The Trac User and Administration Guide?
The Trac User
and
Administration
Guide
This document reproduces the on-line Guide
found at theTrac web site:
http://trac.edgewall.org/wiki/TracGuide
Do not
attempt to print this document on the printers at UAH.
This document is 119 pages long. You will exceed your semester limit, the entire document will not print, and you will be unable to print anything else for the remainder of the semester. You may even loose your computer priviledges.
Web Site: http://trac.edgewall.org/wiki/TracGuide
Table of Contents
The TracGuide is meant to serve as a starting point for all documentation regarding Trac usage and development. The guide is a free document, a collaborative effort, and a part of the Trac Project itself.
Currently available documentation:
If you are looking for a good place to ask a question about Trac, look no further than the MailingList. It provides a friendly environment to discuss openly among Trac users and developers.
See also the TracSupport page for more information resources.
Finally, developer documentation can be found in TracDev and its sub-pages.
NOTE: For installing previous Trac versions, please refer to 0.10/TracInstall.
WARNING: Trac is not currently compatible with Python 2.6 or 3.0.
Trac is written in the Python programming language and needs a database, SQLite, PostgreSQL, or MySQL. For HTML rendering, Trac uses the Genshi templating system.
What follows are generic instructions for installing and setting up Trac and its requirements. While you can find instructions for installing Trac on specific systems at TracInstallPlatforms on the main Trac site, please be sure to first read through these general instructions to get a good understanding of the tasks involved.
For the quick install, make sure you have Python-2.5, easy_install and SQlite-3.3.4 installed (or above). (You also might want to install python-dev to build genshi)
sudo easy_install Trac
The hardware requirements for running Trac obviously depend on the expected data volume (number of wiki pages, tickets, revisions) and traffic. Very small projects will run fine with a 500MHz processor and 128MB RAM using SQLite. In general, the more RAM, the better. A fast hard disk also helps.
To install Trac, the following software packages must be installed:
Note: It appears that PySQLite 2.x is required for Trac 0.9+/SQLite 3.x if you plan to use the 'trac-post-commit-hook.py' script available from the 'contrib' section of the source repository.
Note: Users of Mac OS X please take care; the Apple-supplied SQLite contains additional code to support file locking on network filesystems like AFP or SMB. This is not presently (3.3.6) in the mainline sources, so if you build your own SQLite from source it will not function correctly on such filesystems - typically it gives the error "database is locked". A patch is available for version 3.3.6, based on Apple's code, otherwise you're probably best off using the Apple supplied version (presently 3.1.3).
Warning: PostgreSQL 8.3 uses a strict type checking mechanism. To use Trac with the 8.3 Version of PostgreSQL, you will need trac-0.11 or later.
Warning: MySQL support is currently still experimental. That means it works for some people, but several issues remain, in particular regarding the use of unicode and the key length in the repository cache. See MySqlDb for more detailed information.
Please note: if using Subversion, Trac must be installed on the same machine. Remote repositories are currently not supported.
For those stuck with Apache 1.3, it is also possible to get Trac working with mod_python 2.7 (see TracModPython2.7). This guide hasn't been updated since 0.84, so it may or may not work.
Attention: The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the MailingList or IrcChannel.
Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the platform-specific instructions also describe the installation of the dependencies. Keep in mind however that the information there probably concern older versions of Trac than the one you're installing (there are even some pages that are still talking about Trac 0.8!).
One way to install Trac is using setuptools. With setuptools you can install Trac from the subversion repository; for example, to install release version 0.11 do:
easy_install http://svn.edgewall.org/repos/trac/tags/trac-0.11
But of course the python-typical setup at the top of the source directory also works:
$ python ./setup.py install
Note: you'll need root permissions or equivalent for this step.
This will byte-compile the python source code and install it as an .egg file or folder in the site-packages directory of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as htdocs and templates.
The script will also install the trac-admin command-line tool, used to create and maintain project environments, as well as the tracd standalone server.
To install Trac to a custom location, or find out about other advanced installation options, run:
easy_install --help
Also see Installing Python Modules for detailed information.
Specifically, you might be interested in:
easy_install --prefix=/path/to/installdir
or, if installing Trac to a Mac OS X system:
easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages
The above will place your tracd and trac-admin commands into /usr/local/bin and will install the Trac libraries and dependencies into /Library/Python/2.5/site-packages, which is Apple's preferred location for third-party Python application installations.
A Trac environment is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable configuration file and various other files and directories.
A new environment is created using trac-admin:
$ trac-admin /path/to/myproject initenv
trac-admin will prompt you for the information it needs to create the environment, such as the name of the project, the type and the path to an existing source code repository, the database connection string, and so on. If you're not sure what to specify for one of these options, just leave it blank to use the default value. The database connection string in particular will always work as long as you have SQLite installed. Leaving the path to the source code repository empty will disable any functionality related to version control, but you can always add that back when the basic system is running.
Also note that the values you specify here can be changed later by directly editing the TracIni configuration file.
Note: The user account under which the web server runs will require write permissions to the environment directory and all the files inside. On Linux, with the web server running as user apache and group apache, enter:
chown -R apache.apache /path/to/myproject
Warning: If the trac.cgi files are not installed where you expect, then the current documentation is insufficient; it might be necessary to use the 'deploy' command in trac-admin. See tickets http://trac.edgewall.org/ticket/7312 and possibly http://trac.edgewall.org/ticket/6827
After having created a Trac environment, you can easily try the web interface by running the standalone server tracd:
$ tracd --port 8000 /path/to/myproject
Then, fire up a browser and visit http://localhost:8000/. You should get a simple listing of all environments that tracd knows about. Follow the link to the environment you just created, and you should see Trac in action. If you only plan on managing a single project with trac you can have the standalone server skip the environment list by starting it like this:
$ tracd -s --port 8000 /path/to/myproject
Trac provides three options for connecting to a "real" web server: CGI, FastCGI and mod_python. For decent performance, it is recommended that you use either FastCGI or mod_python.
If you're not afraid of running newer code, you can also try running Trac on mod_wsgi. This should deliver even better performance than mod_python, but the module isn't as extensively tested as mod_python.
Trac also supports AJP which may be your choice if you want to connect to IIS.
Some Python plugins need to be extracted to a cache directory. By default the cache resides in the home directory of the current user. When running Trac on a Web Server as a dedicated user (which is highly recommended) who has no home directory, this might prevent the plugins from starting. To override the cache location you can set the PYTHON_EGG_CACHE environment variable. Refer to your server documentation for detailed instructions.
The process of adding, removing, and configuring user accounts for authentication depends on the specific way you run Trac. The basic procedure is described in the Adding Authentication section on the TracCgi page. To learn how to setup authentication for the frontend you're using, please refer to one of the following pages:
Once you have your Trac site up and running, you should be able to browse your subversion repository, create tickets, view the timeline, etc.
Keep in mind that anonymous (not logged in) users can by default access most but not all of the features. You will need to configure authentication and grant additional permissions to authenticated users to see the full set of features.
A Trac environment needs to be upgraded before it can be used with Trac 0.11. This document describes the steps necessary to upgrade an environment.
Environment upgrades are not necessary for minor version releases unless otherwise noted.
Typically, there are four steps involved in upgrading to a newer version of Trac:
Get the new version as described in TracInstall, or your operating system specific procedure.
If you do a manual (not operating system specific) upgrade, you should also stop any running Trac server before the installation. Doing "hot" upgrades is not advised, especially not on Windows (#7265).
You may also want to remove the pre-existing Trac code by deleting the trac directory from the Python lib/site-packages directory, or remove Trac .eggs from former versions. The location of the site-packages directory depends on the operating system, and the location in which Python was installed. However, the following locations are common:
You may also want to remove the Trac cgi-bin, htdocs, templates and wiki-default directories that are commonly found in a directory called share/trac (the exact location depends on your platform).
This cleanup is not mandatory, but it makes it easier to troubleshoot issues later on, as you won't waste your time looking at code or templates from a previous release that are not being used anymore... As usual, make a backup before actually deleting things.
If you had the webadmin plugin installed, you can now uninstall it as it is now part of the Trac code base.
After restarting, Trac should show the instances which need a manual upgrade via the automated upgrade scripts to ease the pain. These scripts are run via trac-admin:
trac-admin /path/to/projenv upgrade
This command will do nothing if the environment is already up-to-date.
Note that if you are using a PostgreSQL database, this command will fail with the message that the environment can only be backed up when you use an SQLite database. This means that you will have to backup the repository and the database manually. Then, to perform the actual upgrade, run:
trac-admin /path/to/projenv upgrade --no-backup
If you are using custom CSS styles or modified templates in the templates directory of the TracEnvironment, you will need to convert them to the Genshi way of doing things. To continue to use your style sheet, follow the instructions at TracInterfaceCustomization#SiteAppearance.
Every Trac environment includes a copy of the Trac documentation for the installed version. As you probably want to keep the included documentation in sync with the installed version of Trac, trac-admin provides a command to upgrade the documentation:
trac-admin /path/to/projenv wiki upgrade
Note that this procedure will of course leave your WikiStart page intact.
The templating engine has changed in 0.11, please look at TracInterfaceCustomization for more information.
The Trac macros will need to be adapted, as the old-style wiki-macros are not supported anymore (due to the drop of ClearSilver and the HDF); they need to be converted to the new-style macros, see WikiMacros. When they are converted to the new style, they need to be placed into the plugins directory instead and not wiki-macros, which is no longer scanned for macros or plugins.
For those who run Trac under the CGI environment, run this command in order to obtain the trac.cgi file:
trac-admin /path/to/env deploy /deploy/directory/path
This will create a deploy directory with the following two subdirectories: cgi-bin and htdocs. Then update your Apache configuration file httpd.conf with this new trac.cgi location and htdocs location.
If you are not running CGI, reload the new Trac code by restarting your web server.
If you use a trac parent env configuration and one of the plugins in one child does not work, none of the children work.
This can happen in particular with Python 2.3 on Windows when upgrading without uninstalling first. Some modules were previously capitalized and were changed to lower case, e.g. trac/About.py became trac/about.py. You may find such messages in the Trac log:
ERROR: Skipping "trac.about = trac.about": (can't import "No module named about")
Remove the Lib/site-packages/trac folder and reinstall.
trac-admin will not delete or remove pages that were in version 0.10 but now are not in version 0.11, such as WikiMacros.
The sqlite2pg script on trac-hacks.org has been written to assist in migrating a SQLite database to a PostgreSQL database
For upgrades from versions older than Trac 0.10, refer first to trac:wiki:0.10/TracUpgrade.
Note that downgrading from Trac 0.11 to Trac 0.10.4 or 0.10.5 is easy, but has to be done manually, e.g.
$ sqlite3 db/trac.db "update system set value=20 where name='database_version'"
(upgrade can be redone the normal way later on)
Trac is distributed with a powerful command-line configuration tool. This tool can be used to configure and customize your Trac-installation to better fit your needs.
Some of those operations can also be performed via the Admin web interface, an updated version of the WebAdmin plugin now integrated within Trac (since version 0.11).
You can get a comprehensive list of the available options, commands and sub-commands by invoking trac-admin with the help command:.
trac-admin help
Unless you're executing the help, about or version sub-commands, you'll need to specify the path to the TracEnvironment that you want to administer as the first argument, for example:
trac-admin /path/to/projenv wiki list
When passing the environment path as the only argument, trac-admin starts in interactive mode. Commands can then be executed on the selected environment using the prompt, which offers tab-completion (on non-Windows environments, and when the Python readline module is available) and automatic repetition of the last command issued.
Once you're in interactive mode, you can also get help on specific commands or subsets of commands:
For example, to get an explanation of the resync command, run:
> help resync
To get help on all the Wiki-related commands, run:
> help wiki
help
-- Show documentation
initenv
-- Create and initialize a new environment interactively
initenv <projectname> <db> <repostype> <repospath>
-- Create and initialize a new environment from arguments
hotcopy <backupdir>
-- Make a hot backup copy of an environment
resync
-- Re-synchronize trac with the repository
resync <rev>
-- Re-synchronize only the given <rev>
upgrade
-- Upgrade database to current version
deploy <directory>
-- Extract static resources from Trac and all plugins.
permission list [user]
-- List permission rules
permission add <user> <action> [action] [...]
-- Add a new permission rule
permission remove <user> <action> [action] [...]
-- Remove permission rule
wiki list
-- List wiki pages
wiki remove <page>
-- Remove wiki page
wiki export <page> [file]
-- Export wiki page to file or stdout
wiki import <page> [file]
-- Import wiki page from file or stdin
wiki dump <directory>
-- Export all wiki pages to files named by title
wiki load <directory>
-- Import all wiki pages from directory
wiki upgrade
-- Upgrade default wiki pages to current version
ticket remove <number>
-- Remove ticket
ticket_type list
-- Show possible ticket types
ticket_type add <value>
-- Add a ticket type
ticket_type change <value> <newvalue>
-- Change a ticket type
ticket_type remove <value>
-- Remove a ticket type
ticket_type order <value> up|down
-- Move a ticket type up or down in the list
priority list
-- Show possible ticket priorities
priority add <value>
-- Add a priority value option
priority change <value> <newvalue>
-- Change a priority value
priority remove <value>
-- Remove priority value
priority order <value> up|down
-- Move a priority value up or down in the list
severity list
-- Show possible ticket severities
severity add <value>
-- Add a severity value option
severity change <value> <newvalue>
-- Change a severity value
severity remove <value>
-- Remove severity value
severity order <value> up|down
-- Move a severity value up or down in the list
component list
-- Show available components
component add <name> <owner>
-- Add a new component
component rename <name> <newname>
-- Rename a component
component remove <name>
-- Remove/uninstall component
component chown <name> <owner>
-- Change component ownership
version list
-- Show versions
version add <name> [time]
-- Add version
version rename <name> <newname>
-- Rename version
version time <name> <time>
-- Set version date (Format: "YYYY-MM-DD", "now" or "")
version remove <name>
-- Remove version
milestone list
-- Show milestones
milestone add <name> [due]
-- Add milestone
milestone rename <name> <newname>
-- Rename milestone
milestone due <name> <due>
-- Set milestone due date (Format: "YYYY-MM-DD", "now" or "")
milestone completed <name> <completed>
-- Set milestone completed date (Format: "YYYY-MM-DD", "now" or "")
milestone remove <name>
-- Remove milestone
resolution list
-- Show possible ticket resolutions
resolution add <value>
-- Add a resolution value option
resolution change <value> <newvalue>
-- Change a resolution value
resolution remove <value>
-- Remove resolution value
resolution order <value> up|down
-- Move a resolution value up or down in the list
The initenv also supports an extra --inherit option, which can be used to specify the [inherit] file option at environment creation time so that only the options not already specified in the global configuration file will be written in the conf/trac.ini file of the newly created environment. See TracIni#GlobalConfiguration.
Note that in version 0.11 of Trac, initenv lost an extra last argument <templatepath>, which was used in previous versions to point to the templates folder. If you are using the one-liner 'trac-admin /path/to/trac/ initenv <projectname> <db> <repostype> <repospath>' in the above and getting an error that reads 'Wrong number of arguments to initenv: 4', then this is because you're using a trac-admin script from an older version of Trac.
Ticket data can be imported from Bugzilla using the bugzilla2trac.py script, available in the contrib/ directory of the Trac distribution.
$ bugzilla2trac.py
bugzilla2trac - Imports a bug database from Bugzilla into Trac.
Usage: bugzilla2trac.py [options]
Available Options:
--db <MySQL dbname> - Bugzilla's database
--tracenv /path/to/trac/env - full path to Trac db environment
-h | --host <MySQL hostname> - Bugzilla's DNS host name
-u | --user <MySQL username> - effective Bugzilla's database user
-p | --passwd <MySQL password> - Bugzilla's user password
-c | --clean - remove current Trac tickets before importing
--help | help - this help info
Additional configuration options can be defined directly in the script.
Currently, the following data is imported from Bugzilla:
The script provides a number of features to ease the conversion, such as:
For more details on the available options, see the configuration section at the top of the script.
Ticket data can be imported from Sourceforge using the sourceforge2trac.py script, available in the contrib/ directory of the Trac distribution.
NB! The mantis2trac script now lives at http://trac-hacks.org/wiki/MantisImportScript . You can always get the latest version from http://trac-hacks.org/changeset/latest/mantisimportscript?old_path=/&filename=mantisimportscript&format=zip
Mantis bugs can be imported using the attached script.
Currently, the following data is imported from Mantis:
If you use the script, please read the NOTES section (at the top of the file) and make sure you adjust the config parameters for your environment.
mantis2trac.py has the same parameters as the bugzilla2trac.py script:
mantis2trac - Imports a bug database from Mantis into Trac.
Usage: mantis2trac.py [options]
Available Options:
--db <MySQL dbname> - Mantis database
--tracenv /path/to/trac/env - Full path to Trac db environment
-h | --host <MySQL hostname> - Mantis DNS host name
-u | --user <MySQL username> - Effective Mantis database user
-p | --passwd <MySQL password> - Mantis database user password
-c | --clean - Remove current Trac tickets before importing
--help | help - This help info
Additional configuration options can be defined directly in the script.
Since trac uses a SQL database to store the data, you can import from other systems by examining the database tables. Just go into sqlite command line to look at the tables and import into them from your application.
See http://trac.edgewall.org/attachment/wiki/TracSynchronize/csv2trac.2.py for details. This approach is particularly useful if one needs to enter a large number of tickets by hand. (note that the ticket type type field, (task etc...) is also needed for this script to work with more recent Trac releases)
[Note To Editors] Please discuss documentation changes in the #Discussion section. Even better, send us documentation patches against the code (i.e. where the configuration entries are documented), either on Trac-dev or on new tickets.
Trac configuration is done by editing the trac.ini config file, located in <projectenv>/conf/trac.ini. Changes to the configuration are usually reflected immediately, though changes to the [components] or [logging] sections will require restarting the web server. You may also need to restart the web server after creating a global configuration file when none was previously present.
Global Configuration?
In versions prior to 0.11, the global configuration was by default located in $prefix/share/trac/conf/trac.ini or sometimes /etc/trac/trac.ini depending on the distribution. If you're upgrading, you may want to specify that file to inherit from. Literally, when you're upgrading to 0.11, you have to add an inherit-section to your project's trac.ini file. Additionally you have to move your customized templates and common images from $prefix/share/trac/... to the new location.
Global options will be merged with the environment-specific options, where local options override global options. The options file is specified as follows:
[inherit]
file = /usr/share/trac/conf/trac.ini
Note that you can also specify a global option file when creating a new project, by adding the option --inherit=/path/to/global/options to trac-admin's initenv command. If you would not do this but nevertheless intend to use a global option file with your new environment, you would have to go through the newly generated conf/trac.ini file and delete the entries that would otherwise override those set in the global file.
Reference?
This is a brief reference of available configuration options.
[attachment]?
|
[bitten]?
|
[browser]?
|
[changeset]?
|
[header_logo]?
|
[inherit]?
|
[logging]?
|
[milestone]?
|
[mimeviewer]?
|
[notification]?
|
[project]?
|
[query]?
|
[report]?
|
[revisionlog]?
|
[roadmap]?
|
[search]?
|
[spam-filter]?
|
[svn]?
|
[ticket]?
|
[timeline]?
|
[trac]?
|
[vote]?
|
[wiki]?
|
[components]?
This section is used to enable or disable components provided by plugins, as well as by Trac itself. The component to enable/disable is specified via the name of the option. Whether its enabled is determined by the option value; setting the value to enabled or on will enable the component, any other value (typically disabled or off) will disable the component.
The option name is either the fully qualified name of the components or the module/package prefix of the component. The former enables/disables a specific component, while the latter enables/disables any component in the specified package/module.
Consider the following configuration snippet:
[components]
trac.ticket.report.ReportModule = disabled
webadmin.* = enabled
The first option tells Trac to disable the report module. The second option instructs Trac to enable all components in the webadmin package. Note that the trailing wildcard is required for module/package matching.
See the Plugins page on About Trac to get the list of active components (requires CONFIG_VIEW permissions.)
See also: TracPlugins
[ticket-custom]?
In this section, you can define additional fields for tickets. See TracTicketsCustomFields for more details.
[ticket-workflow]?
(since 0.11)
The workflow for tickets is controlled by plugins. By default, there's only a ConfigurableTicketWorkflow component in charge. That component allows the workflow to be configured via this section in the trac.ini file. See TracWorkflow for more details.
[milestone-groups]?
(since 0.11)
As the workflow for tickets is now configurable, there can be many ticket states, and simply displaying closed tickets vs. all the others is maybe not appropriate in all cases. This section enables one to easily create groups of states that will be shown in different colors in the milestone progress bar.
Example configuration (the default only has closed and active):
closed = closed
closed.order = 0 # sequence number in the progress bar
closed.query_args = group=resolution # optional extra param for the query
closed.overall_completion = true # indicates groups that count for overall completion percentage
new = new
new.order = 1
new.css_class = new
new.label = new
active = * # one catch-all group is allowed
active.order = 1
active.css_class = open # CSS class for this interval
active.label = in progress # Displayed label for this group
The definition consists in a comma-separated list of accepted status. Also, '*' means any status and could be used to associate all remaining states to one catch-all group.
The CSS class can be one of: new (yellow), open (no color) or closed (green). New styles can easily be added using the following selector: table.progress td.<class>
[svn:externals]?
(since 0.11)
The TracBrowser for Subversion can interpret the svn:externals property of folders out of the box. However, if those externals are not using the http: protocol, or if a link to a different repository browser (such another Trac or ViewVC) is desired, then Trac needs to be able to map an external prefix to this other URL.
This mapping is done in the [svn:externals] section of the TracIni
Example:
[svn:externals]
1 = svn://server/repos1 http://trac/proj1/browser/$path?rev=$rev
2 = svn://server/repos2 http://trac/proj2/browser/$path?rev=$rev
3 = http://theirserver.org/svn/eng-soft http://ourserver/viewvc/svn/$path/?pathrev=25914
4 = svn://anotherserver.com/tools_repository http://ourserver/trac/support/browser/$path?rev=$rev
With the above, the svn://anotherserver.com/tools_repository/tags/1.1/tools external will be mapped to http://ourserver/trac/support/browser/tags/1.1/tools?rev= (and rev will be set to the appropriate revision number if the external additionally specifies a revision, see the SVN Book on externals for more details).
Note that the number used as a key in the above section is purely used as a place holder, as the URLs themselves can't be used as a key due to various limitations in the configuration file parser.
Discussion?
More detail on getting [svn:externals] to work would be appreciated. A link to a working example would probably help a lot too.
Please discuss documentation change here. Even better, send us documentation patches against the code, either on Trac-dev or on new tickets.
Trac uses a simple, case sensitive, permission system to control what users can and can't access.
Permission privileges are managed using the trac-admin tool or (new in version 0.11) the General / Permissions panel in the Admin tab of the web interface.
In addition to the default permission policy described in this page, it is possible to activate additional permission policies by enabling plugins and listing them in the [trac] permission_policies configuration entry in the TracIni. See TracFineGrainedPermissions for more details.
Non-authenticated users accessing the system are assigned the name "anonymous". Assign permissions to the "anonymous" user to set privileges for anonymous/guest users. The parts of Trac that a user does not have the privileges for will not be displayed in the navigation. In addition to these privileges, users can be granted additional individual rights in effect when authenticated and logged into the system. All logged in users belong to the virtual group "authenticated", which inherits permissions from "anonymous".
This feature is new in version 0.11.
To access this tab, a user must have TRAC_ADMIN privileges. This can be performed as follows (more on the trac-admin script below):
$ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
Then, the user will be able to see the Admin tab, and can then access the permissions menu. This menu will allow you to perform all the following actions, but from the browser without requiring root access to the server (just the correct permissions for your user account).
An easy way to quickly secure a new Trac install is to run the above command on the anonymous user, install the AccountManagerPlugin, create a new admin account graphically and then remove the TRAC_ADMIN permission from the anonymous user.
To enable all privileges for a user, use the TRAC_ADMIN permission. Having TRAC_ADMIN is like being root on a *NIX system: it will allow you to perform any operation.
Otherwise, individual privileges can be assigned to users for the various different functional areas of Trac (note that the privilege names are case-sensitive):
|
|
Attention: the "view tickets" button appears with the REPORT_VIEW permission.
|
|
|
|
|
You grant privileges to users using trac-admin. The current set of privileges can be listed with the following command:
$ trac-admin /path/to/projenv permission list
This command will allow the user bob to delete reports:
$ trac-admin /path/to/projenv permission add bob REPORT_DELETE
The permission add command also accepts multiple privilege names:
$ trac-admin /path/to/projenv permission add bob REPORT_DELETE WIKI_CREATE
Or add all privileges:
$ trac-admin /path/to/projenv permission add bob TRAC_ADMIN
There are two built-in groups, "authenticated"
and "anonymous".
Any user who has not logged in is automatically in the "anonymous"
group.
Any user who has logged in is also in the "authenticated"
group.
The "authenticated" group inherits permissions from the "anonymous"
group.
eg. if the "anonymous" group has permission WIKI_MODIFY, it's
not necessary to add the WIKI_MODIFY permisison to the "authenticated"
group as well.
Custom groups may be defined that inherit permissions from the two built-in groups.
Permissions can be grouped together to form roles such as developer, admin, etc.
$ trac-admin /path/to/projenv permission add developer WIKI_ADMIN
$ trac-admin /path/to/projenv permission add developer REPORT_ADMIN
$ trac-admin /path/to/projenv permission add developer TICKET_MODIFY
$ trac-admin /path/to/projenv permission add bob developer
$ trac-admin /path/to/projenv permission add john developer
Group membership can be checked by doing a permission list with no further arguments; the resulting output will include group memberships. Use lowercase for group names, as uppercase is reserved for permissions.
Permission groups can be created by assigning a user to a group you wish to create, then assign permissions to that group.
The following will add bob to the new group called beta_testers and then will assign WIKI_ADMIN permissions to that group. (Thus, bob will inherit the WIKI_ADMIN permission)
$ trac-admin /path/to/projenv permission add bob beta_testers
$ trac-admin /path/to/projenv permission add beta_testers WIKI_ADMIN
Permissions can be removed using the 'remove' command. For example:
This command will prevent the user bob from deleting reports:
$ trac-admin /path/to/projenv permission remove bob REPORT_DELETE
Just like permission add, this command accepts multiple privilege names.
You can also remove all privileges for a specific user:
$ trac-admin /path/to/projenv permission remove bob '*'
Or one privilege for all users:
$ trac-admin /path/to/projenv permission remove '*' REPORT_ADMIN
By default on a new Trac installation, the anonymous user will have view access to everything in Trac, but will not be able to create or modify anything. On the other hand, the authenticated users will have the permissions to create and modify tickets and wiki pages.
anonymous
BROWSER_VIEW CHANGESET_VIEW FILE_VIEW LOG_VIEW MILESTONE_VIEW REPORT_SQL_VIEW REPORT_VIEW ROADMAP_VIEW SEARCH_VIEW TICKET_VIEW TIMELINE_VIEW WIKI_VIEW
authenticated
TICKET_CREATE TICKET_MODIFY WIKI_CREATE WIKI_MODIFY
This page is meant to give users suggestions on how they can customize the look of Trac. Topics on this page cover editing the HTML templates and CSS files, but not the program code itself. The topics are intended to show users how they can modify the look of Trac to meet their specific needs. Suggestions for changes to Trac's interface applicable to all users should be filed as tickets, not listed on this page.
The easiest parts of the Trac interface to customize are the logo and the site icon. Both of these can be configured with settings in trac.ini.
The logo or icon image should be put in a folder named "htdocs" in your project's environment folder. (Note: in projects created with a Trac version prior to 0.9 you will need to create this folder)
Note: you can actually put the logo and icon anywhere on your server (as long as it's accessible through the web server), and use their absolute or server-relative URLs in the configuration.
Now configure the appropriate section of your trac.ini:
Change the src setting to site/ followed by the name of your image file. The width and height settings should be modified to match your image's dimensions (the Trac chrome handler uses "site/" for files within the project directory htdocs and "common/" for the common ones).
[header_logo]
src = site/my_logo.gif
alt = My Project
width = 300
height = 100
Icons should be a 16x16 image in .gif or .ico format. Change the icon setting to site/ followed by the name of your icon file. Icons will typically be displayed by your web browser next to the site's URL and in the Bookmarks menu.
[project]
icon = site/my_icon.ico
Note though that this icon is ignored by Internet Explorer, which only accepts a file named favicon.ico at the root of the host. To make the project icon work in both IE and other browsers, you can store the icon in the document root of the host, and reference it from trac.ini as follows:
[project]
icon = /favicon.ico
The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones).
In the following example, we rename the link to the Wiki start "Home", and hide the "Help/Guide". We also make the "View Tickets" entry link to a specific report .
[mainnav]
wiki.label = Home
tickets.href = /report/24
[metanav]
help = disabled
See also TracNavigation for a more detailed explanation of the mainnav and metanav terms.
Trac is using Genshi as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.
Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as 'site.html' inside your projects templates directory (each Trac project can have their own site.html), e.g. /path/to/env/templates/site.html:
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:py="http://genshi.edgewall.org/"
py:strip="">
<!--! Add site-specific style sheet -->
<head py:match="head" py:attrs="select('@*')">
${select('*|comment()|text()')}
<link rel="stylesheet" type="text/css"
href="${href.chrome('site/style.css')}" />
</head>
<body py:match="body" py:attrs="select('@*')">
<!--! Add site-specific header -->
<div id="siteheader">
<!--! Place your header content here... -->
</div>
${select('*|text()')}
<!--! Add site-specific footer -->
<div id="sitefooter">
<!--! Place your footer content here... -->
</div>
</body>
</html>
Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example ${href.chrome('site/style.css')} attribute references template placed into environment's htdocs/ In a similar fashion ${chrome.htdocs_location} is used to specify common htdocs/ directory from Trac installation.
site.html is one file to contain all your modifications. It usually works by the py:match (element of attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find and modify them. A site.html can contain any number of such py:match sections for whatever you need to modify. This is all Genshi, so the docs on the exact syntax can be found there.
Example snippet of adding introduction text to the new ticket form (hide when preview):
<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
<py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
<p>Please make sure to search for existing tickets before reporting a new one!</p>
</py:if>
${select('*')}
</form>
This example illustrates a technique of using req.environ['PATH_INFO'] to limit scope of changes to one view only. For instance, to make changes in site.html only for timeline and avoid modifying other sections - use req.environ['PATH_INFO'] == '/timeline' condition in <py:if> test.
If the environment is upgraded from 0.10 and a site_newticket.cs file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a <div> block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others:
<form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')"
xmlns:xi="http://www.w3.org/2001/XInclude">
<py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
<xi:include href="site_newticket.cs"><xi:fallback /></xi:include>
</py:if>
${select('*')}
</form>
Also note that the site.html (despite its name) can be put in a common templates directory - see the [inherit] templates_dir option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global site.html file can be made to include any existing header, footer and newticket snippets.
You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects.
The following is the basic template used by Trac to display a list of links to the projects. For projects that could not be loaded it displays an error message. You can use this as a starting point for your own index template.
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:py="http://genshi.edgewall.org/"
xmlns:xi="http://www.w3.org/2001/XInclude">
<head>
<title>Available Projects</title>
</head>
<body>
<h1>Available Projects</h1>
<ul>
<li py:for="project in projects" py:choose="">
<a py:when="project.href" href="$project.href"
title="$project.description">$project.name</a>
<py:otherwise>
<small>$project.name: <em>Error</em> <br /> ($project.description)</small>
</py:otherwise>
</li>
</ul>
</body>
</html>
Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11):
For FastCGI:
FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects \
-initial-env TRAC_ENV_INDEX_TEMPLATE=/path/to/template
For mod_python:
PythonOption TracEnvParentDir /parent/dir/of/projects
PythonOption TracEnvIndexTemplate /path/to/template
For CGI:
SetEnv TRAC_ENV_INDEX_TEMPLATE /path/to/template
For TracStandalone, you'll need to set up the TRAC_ENV_INDEX_TEMPLATE environment variable in the shell used to launch tracd:
The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by the same server. The recommended way is to use a site.html template (see #SiteAppearance) whenever possible. Using site.html means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of theme.html or any other Trac template, you need to migrate your modifiations to the newer version - if not, new Trac features or bug fixes may not work as expected.
With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, .../trac/ticket/templates, .../trac/wiki/templates, ++). The #ProjectList template file is called index.html, while the template responsible for main layout is called theme.html. Page assets such as images and CSS style sheets are located in the egg's trac/htdocs directory.
However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of two alternatives:
Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.
Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server.
Since version 0.9, Trac supports plugins that extend the built-in functionality. The plugin functionality is based on the component architecture.
To use egg based plugins in Trac, you need to have setuptools (version 0.6) installed.
To install setuptools, download the bootstrap module ez_setup.py and execute it as follows:
$ python ez_setup.py
If the ez_setup.py script fails to install the setuptools release, you can download it from PyPI and install it manually.
Plugins can also consist of a single .py file dropped into either the environment or global plugins directory (since 0.10). See TracIni#GlobalConfiguration .
Plugins are packaged as Python eggs. That means they are ZIP archives with the file extension .egg.
If you have downloaded a source distribution of a plugin, and want to build the .egg file, follow this instruction:
- $ python setup.py bdist_egg
Then you will have a *.egg file. Examine the output of running python to find where this was created.
Once you have the plugin archive, you need to copy it into the plugins directory of the project environment. Also, make sure that the web server has sufficient permissions to read the plugin egg. Then, restart the web server (this requirement was not previously mentioned in this document, but in my tests it began working only after I did so).
To uninstall a plugin installed this way, remove the egg from plugins directory and restart web server.
Note that the Python version that the egg is built with must match the Python version with which Trac is run. If for instance you are running Trac under Python 2.3, but have upgraded your standalone Python to 2.4, the eggs won't be recognized.
Note also that in a multi-project setup, a pool of Python interpreter instances will be dynamically allocated to projects based on need, and since plugins occupy a place in Python's module system, the first version of any given plugin to be loaded will be used for all the projects. In other words, you cannot use different versions of a single plugin in two projects of a multi-project setup. It may be safer to install plugins for all projects (see below) and then enable them selectively on a project-by-project basis.
Some plugins (such as SpamFilter) are downloadable as a .egg file which can be installed with the easy_install program:
easy_install TracSpamFilter
If easy_install is not on your system see the Requirements section above to install it. Windows users will need to add the Scripts directory of their Python installation (for example, C:\Python23\Scripts) to their PATH environment variable (see easy_install Windows notes for more information).
If Trac reports permission errors after installing a zipped egg and you would rather not bother providing a egg cache directory writable by the web server, you can get around it by simply unzipping the egg. Just pass --always-unzip to easy_install:
easy_install --always-unzip TracSpamFilter-0.2.1dev_r5943-py2.4.egg
You should end up with a directory having the same name as the zipped egg (complete with .egg extension) and containing its uncompressed contents.
Trac also searches for globally installed plugins (since 0.10), see TracIni#GlobalConfiguration.
easy_install makes installing from source a snap. Just give it the URL to either a Subversion repository or a tarball/zip of the source:
easy_install http://svn.edgewall.com/repos/trac/sandbox/spam-filter
Unlike plugins installed per-environment, you'll have to explicitly enable globally installed plugins via trac.ini. This also applies to plugins installed in the path specified in the [inherit] plugins_dir configuration option. This is done in the [components] section of the configuration file, for example:
[components]
tracspamfilter.* = enabled
The name of the option is the Python package of the plugin. This should be specified in the documentation of the plugin, but can also be easily discovered by looking at the source (look for a top-level directory that contains a file named __init__.py.)
Note: After installing the plugin, you need to restart your web server.
easy_install or python setup.py does not have an uninstall feature. Hower, it is usually quite trivial to remove a globally installed egg and reference:
If you are uncertain about the location of the egg, here is a small tip to help locate an egg (or any package) - replace myplugin with whatever namespace the plugin uses (as used when enabling the plugin):
>>> import myplugin
>>> print myplugin.__file__
/opt/local/python24/lib/site-packages/myplugin-0.4.2-py2.4.egg/myplugin/__init__.pyc
Some plugins will need to be extracted by the Python eggs runtime (pkg_resources), so that their contents are actual files on the file system. The directory in which they are extracted defaults to the home directory of the current user, which may or may not be a problem. You can however override the default location using the PYTHON_EGG_CACHE environment variable.
To do this from the Apache configuration, use the SetEnv directive as follows:
SetEnv PYTHON_EGG_CACHE /path/to/dir
This works whether you are using the CGI or the mod_python front-end. Put this directive next to where you set the path to the Trac environment, i.e. in the same <Location> block.
For example (for CGI):
<Location /trac>
SetEnv TRAC_ENV /path/to/projenv
SetEnv PYTHON_EGG_CACHE /path/to/dir
</Location>
or (for mod_python):
<Location /trac>
SetHandler mod_python
...
SetEnv PYTHON_EGG_CACHE /path/to/dir
</Location>
Note: SetEnv requires the mod_env module which needs to be activated for Apache. In this case the SetEnv directive can also be used in the mod_python Location block.
For FastCGI, you'll need to -initial-env option, or whatever is provided by your web server for setting environment variables.
Note: that if you already use -initial-env to set the project directory for either a single project or parent you will need to add an additional -initial-env directive to the FastCgiConfig directive. I.e.
FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache
If you have set up some subversion hook scripts that call the Trac engine - such as the post-commit hook script provided in the /contrib directory - make sure you define the PYTHON_EGG_CACHE environment variable within these scripts as well.
Try this from the command line:
$ python -c "import pkg_resources"
If you get no output, setuptools is installed. Otherwise, you'll need to install it before plugins will work in Trac.
Python eggs have the Python version encoded in their filename. For example, MyPlugin-1.0-py2.4.egg is an egg for Python 2.4, and will not be loaded if you're running a different Python version (such as 2.3 or 2.5).
Also, verify that the egg file you downloaded is indeed a ZIP archive. If you downloaded it from a Trac site, chances are you downloaded the HTML preview page instead.
If you install a plugin globally (i.e. not inside the plugins directory of the Trac project environment) you will have to explicitly enable it in trac.ini. Make sure that:
Trac must be able to read the file.
Enable logging and set the log level to DEBUG, then watch the log file for messages about loading plugins.
Some plugins require you have special permissions in order to use them. WebAdmin, for example, requires the user to have TRAC_ADMIN permissions for it to show up on the navigation bar.
If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules:
OK, so the logs don't mention plugins, the egg is readable, the python version is correct and the egg has been installed globally (and is enabled in the trac.ini) and it still doesn't work or give any error messages or any other indication as to why? Hop on the IrcChannel and ask away.
Trac supports logging of system messages using the standard logging module that comes with Python.
Logging is configured in the [logging] section in trac.ini.
The log method is set using the log_type option in trac.ini, which takes any of the following values:
none
Suppress all log messages.
file
Log messages to a file, specified with the log_file option in trac.ini.
stderr
Output all log entries to console (tracd only).
syslog
(UNIX) Send all log messages to the local syslogd via named pipe /dev/log. By default, syslog will write them to the file /var/log/messages.
eventlog
(Windows) Use the system's NT Event Log for Trac logging.
The verbosity level of logged messages can be set using the log_level option in trac.ini. The log level defines the minimum level of urgency required for a message to be logged, and those levels are:
CRITICAL
Log only the most critical (typically fatal) errors.
ERROR
Log failures, bugs and errors.
WARN
Log warnings, non-interrupting events.
INFO
Diagnostic information, log information about all processing.
DEBUG
Trace messages, profiling, etc.
Starting with Trac 0.10.4 (see #2844), it is possible to set the output format for log entries. This can be done through the log_format option in trac.ini. The format is a string which can contain any of the Python logging Formatter variables. Additonally, the following Trac-specific variables can be used:
$(basename)s
The last path component of the current environment.
$(path)s
The absolute path for the current environment.
$(project)s
The originating project's name.
Note that variables are identified using a dollar sign ($(...)s) instead of percent sign (%(...)s).
The default format is:
log_format = Trac[$(module)s] $(levelname)s: $(message)s
In a multi-project environment where all logs are sent to the same place (e.g. syslog), it makes sense to add the project name. In this example we use basename since that can generally be used to identify a project:
log_format = Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s
Trac supports notification about ticket changes via email.
Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the Trac-tickets mailing list is set up.
Disabled by default, notification can be activated and configured in trac.ini.
When reporting a new ticket or adding a comment, enter a valid email address in the reporter, assigned to/owner or cc field. Trac will automatically send you an email when changes are made to the ticket (depending on how notification is configured).
This is useful to keep up-to-date on an issue or enhancement request that interests you.
These are the available options for the [notification] section in trac.ini.
Either smtp_from or smtp_replyto (or both) must be set, otherwise Trac refuses to send notification mails.
[notification]
smtp_enabled = true
smtp_server = mail.example.com
smtp_from = notifier@example.com
smtp_replyto = myproj@projects.example.com
smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
#42: testing
---------------------------+------------------------------------------------
Id: 42 | Status: assigned
Component: report system | Modified: Fri Apr 9 00:04:31 2004
Severity: major | Milestone: 0.9
Priority: lowest | Version: 0.6
Owner: anonymous | Reporter: jonas@example.com
---------------------------+------------------------------------
Changes:
* component: changset view => search system
* priority: low => highest
* owner: jonas => anonymous
* cc: daniel@example.com =>
daniel@example.com, jonas@example.com
* status: new => assigned
Comment:
I'm interested too!
--
Ticket URL: <http://example.com/trac/ticket/42>
My Project <http://myproj.example.com/>
Use the following configuration snippet
[notification]
smtp_enabled = true
use_tls = true
mime_encoding = base64
smtp_server = smtp.gmail.com
smtp_port = 587
smtp_user = user
smtp_password = password
where user and password match an existing GMail account, i.e. the ones you use to log in on http://gmail.com
Alternatively, you can use smtp_port = 25.
You should not use smtp_port
= 465. It will not work and your
ticket submission may deadlock. Port 465 is reserved for the SMTPS protocol,
which is not supported by Trac. See #7107 for details.
In Gmail, use the filter:
from:(<smtp_from>) (("Reporter: <username>" -Changes) OR "Changes (by <username>)")
to delete these notifications.
In Thunderbird, there is no such solution if you use IMAP (see http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body).
The best you can do is to set "always_notify_updater" in conf/trac.ini to false. You will however still get an email if you comment a ticket that you own or have reported.
You can also add this plugin: http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin
If you cannot get the notification working, first make sure the log is activated and have a look at the log to find if an error message has been logged. See TracLogging for help about the log feature.
Notification errors are not reported through the web interface, so the user who submit a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace.
Typical error message:
...
File ".../smtplib.py", line 303, in connect
raise socket.error, msg
error: (13, 'Permission denied')
This error usually comes from a security settings on the server: many Linux distributions do not let the web server (Apache, ...) to post email message to the local SMTP server.
Many users get confused when their manual attempts to contact the SMTP server succeed:
telnet localhost 25
The trouble is that a regular user may connect to the SMTP server, but the web server cannot:
sudo -u www-data telnet localhost 25
In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help browsing the Trac MailingList archive.
Relevant ML threads:
Some SMTP servers may reject the notification email sent by Trac.
The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger false positive SPAM detection on sensitive email servers. In such an event, it is recommended to change the default encoding to "quoted-printable" using the mime_encoding option.
Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, it is recommended to stick with the Base64 encoding.
The Trac issue database provides a configurable workflow.
When you run trac-admin <env> upgrade, your trac.ini will be modified to include a [ticket-workflow] section. The workflow configured in this case is the original workflow, so that ticket actions will behave like they did in 0.10.
Graphically, that looks like this:
There are some significant "warts" in this; such as accepting a ticket sets it to 'assigned' state, and assigning a ticket sets it to 'new' state. Perfectly obvious, right? So you will probably want to migrate to "basic" workflow; contrib/workflow/migrate_original_to_basic.py may be helpful.
When a new environment is created, a default workflow is configured in your trac.ini. This workflow is the basic workflow (described in basic-workflow.ini), which is somewhat different from the workflow of the 0.10 releases.
Graphically, it looks like this:
There are several example workflows provided in the Trac source tree; look in contrib/workflow for .ini config sections. One of those may be a good match for what you want. They can be pasted into the [ticket-workflow] section of your trac.ini file.
Here are some diagrams of the above examples.
Create a [ticket-workflow] section in trac.ini. Within this section, each entry is an action that may be taken on a ticket. For example, consider the accept action from simple-workflow.ini:
accept = new,accepted -> accepted
accept.permissions = TICKET_MODIFY
accept.operations = set_owner_to_self
The first line in this example defines the accept action, along with the states the action is valid in (new and accepted), and the new state of the ticket when the action is taken (accepted). The accept.permissions line specifies what permissions the user must have to use this action. The accept.operations line specifies changes that will be made to the ticket in addition to the status change when this action is taken. In this case, when a user clicks on accept, the ticket owner field is updated to the logged in user. Multiple operations may be specified in a comma separated list.
The available operations are:
- Example:
- resolve_new = new -> closed
- resolve_new.name = resolve
- resolve_new.operations = set_resolution
- resolve_new.permissions = TICKET_MODIFY
- resolve_new.set_resolution = invalid,wontfix
Note: Specifying conflicting operations (such as set_owner and del_owner) has unspecified results.
resolve_accepted = accepted -> closed
resolve_accepted.name = resolve
resolve_accepted.permissions = TICKET_MODIFY
resolve_accepted.operations = set_resolution
In this example, we see the .name attribute used. The action here is resolve_accepted, but it will be presented to the user as resolve.
For actions that should be available in all states, * may be used in place of the state. The obvious example is the leave action:
leave = * -> *
leave.operations = leave_status
leave.default = 1
This also shows the use of the .default attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest .default value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing .default values. If not specified for an action, .default is 0. The value may be negative.
There are a couple of hard-coded constraints to the workflow. In particular, tickets are created with status new, and tickets are expected to have a closed state. Further, the default reports/queries treat any state other than closed as an open state.
While creating or modifying a ticket workfow, contrib/workflow/workflow_parser.py may be useful. It can create .dot files that GraphViz understands to provide a visual description of the workflow.
This can be done as follows (your install path may be different).
cd /var/local/trac_devel/contrib/workflow/
sudo ./showworkflow /srv/trac/PlannerSuite/conf/trac.ini
And then open up the resulting trac.pdf file created by the script (it will be in the same directory as the trac.ini file).
After you have changed a workflow, you need to restart apache for the changes to take effect. This is important, because the changes will still show up when you run your script, but all the old workflow steps will still be there until the server is restarted.
By adding the following to your [ticket-workflow] section of trac.ini you get optional testing. When the ticket is in new, accepted or needs_work status you can choose to submit it for testing. When it's in the testing status the user gets the option to reject it and send it back to needs_work, or pass the testing and send it along to closed. If they accept it then it gets automatically marked as closed and the resolution is set to fixed. Since all the old work flow remains, a ticket can skip this entire section.
testing = new,accepted,needs_work,assigned,reopened -> testing
testing.name = Submit to reporter for testing
testing.permissions = TICKET_MODIFY
reject = testing -> needs_work
reject.name = Failed testing, return to developer
pass = testing -> closed
pass.name = Passes Testing
pass.operations = set_resolution
pass.set_resolution = fixed
Sometimes Trac is used in situations where "testing" can mean different things to different people so you may want to create an optional workflow state that is between the default workflow's assigned and closed states, but does not impose implementation-specific details. The only new state you need to add for this is a reviewing state. A ticket may then be "submitted for review" from any state that it can be reassigned. If a review passes, you can re-use the resolve action to close the ticket, and if it fails you can re-use the reassign action to push it back into the normal workflow.
The new reviewing state along with its associated review action looks like this:
review = new,assigned,reopened -> reviewing
review.operations = set_owner
review.permissions = TICKET_MODIFY
Then, to integrate this with the default Trac 0.11 workflow, you also need to add the reviewing state to the accept and resolve actions, like so:
accept = new,reviewing -> assigned
[…]
resolve = new,assigned,reopened,reviewing -> closed
Optionally, you can also add a new action that allows you to change the ticket's owner without moving the ticket out of the reviewing state. This enables you to reassign review work without pushing the ticket back to the new status.
reassign_reviewing = reviewing -> *
reassign_reviewing.name = reassign review
reassign_reviewing.operations = set_owner
reassign_reviewing.permissions = TICKET_MODIFY
The full [ticket-workflow] configuration will thus look like this:
[ticket-workflow]
accept = new,reviewing -> assigned
accept.operations = set_owner_to_self
accept.permissions = TICKET_MODIFY
leave = * -> *
leave.default = 1
leave.operations = leave_status
reassign = new,assigned,reopened -> new
reassign.operations = set_owner
reassign.permissions = TICKET_MODIFY
reopen = closed -> reopened
reopen.operations = del_resolution
reopen.permissions = TICKET_CREATE
resolve = new,assigned,reopened,reviewing -> closed
resolve.operations = set_resolution
resolve.permissions = TICKET_MODIFY
review = new,assigned,reopened -> reviewing
review.operations = set_owner
review.permissions = TICKET_MODIFY
reassign_reviewing = reviewing -> *
reassign_reviewing.operations = set_owner
reassign_reviewing.name = reassign review
reassign_reviewing.permissions = TICKET_MODIFY
The above resolve_new operation allows you to set the possible resolutions for a new ticket. By modifying the existing resolve action and removing the new status from before the -> we then get two resolve actions. One with limited resolutions for new tickets, and then the regular one once a ticket is accepted.
resolve_new = new -> closed
resolve_new.name = resolve
resolve_new.operations = set_resolution
resolve_new.permissions = TICKET_MODIFY
resolve_new.set_resolution = invalid,wontfix,duplicate
resolve = assigned,accepted,reopened -> closed
resolve.operations = set_resolution
resolve.permissions = TICKET_MODIFY
If the customization above is not extensive enough for your needs, you can extend the workflow using plugins. These plugins can provide additional operations for the workflow (like code_review), or implement side-effects for an action (such as triggering a build) that may not be merely simple state changes. Look at sample-plugins/workflow for a few simple examples to get started.
But if even that is not enough, you can disable the ConfigurableTicketWorkflow component and create a plugin that completely replaces it.
If you add additional states to your workflow, you may want to customize your milestone progress bars as well. See TracIni.
New enhancement ideas for the workflow system should be filed as enhancement tickets against the ticket system component. If desired, add a single-line link to that ticket here. Also look at the TracHacks:wiki:AdvancedTicketWorkflowPlugin as it provides experimental operations.
If you have a response to the comments below, create an enhancement ticket, and replace the description below with a link to the ticket.
This appears to add complexity without adding functionality; please provide a detailed example where these additions allow something currently impossible to implement.
A workflow plugin can add an arbitrary workflow operation, so this is already possible.
This is either duplicating the existing set_owner operation, or needs to be clarified.
Look into the TracHacks:wiki:AdvancedTicketWorkflowPlugin's triage operation.
Trac has a built-in wiki engine, used for text and documentation throughout the system. WikiFormatting is used in wiki pages, tickets and check-in log messages. This allows for formatted text and hyperlinks in and between all Trac modules.
Editing wiki text is easy, using any web browser and a simple formatting system, rather than more complex markup languages like HTML. The reasoning behind its design is that HTML, with its large collection of nestable tags, is too complicated to allow fast-paced editing, and distracts from the actual content of the pages. Note though that Trac also supports HTML, reStructuredText and Textile as alternative markup formats.
The main goal of the wiki is to make editing text easier and encourage people to contribute and annotate text content for a project.
The wiki itself does not enforce any structure, but rather resembles a stack of empty sheets of paper, where you can organize information and documentation as you see fit, and later reorganize if necessary.
For more help on editing wiki text, see these pages:
If you want to practice editing, please use the SandBox.
Some more information about wiki on the web:
See also: TracGuide
The timeline provides a historic view of the project in a single report.
It lists all Trac events that have occurred in chronological order, a brief description of each event and if applicable, the person responsible for the change.
The timeline lists these kinds of events:
Each event entry provides a hyperlink to the specific event in question, as well as a brief excerpt of the actual comment or text, if available.
See TracIni for timeline configuration options.
The Timeline module supports subscription using RSS 2.0 syndication. To subscribe to project events, click the orange XML icon at the bottom of the page. See TracRss for more information on RSS support in Trac.
Several of the Trac modules support content syndication using the RSS (Really Simple Syndication) XML format. Using the RSS subscription feature in Trac, you can easily monitor progress of the project, a set of issues or even changes to a single file.
Trac supports RSS feeds in:
Anywhere in Trac where RSS is available, you should find a small orange XML icon, typically placed at the bottom of the page. Clicking the icon will access the RSS feed for that specific resource.
Note: Different modules provide different data in their RSS feeds. Usually, the syndicated information corresponds to the current view. For example, if you click the RSS link on a report page, the feed will be based on that report. It might be explained by thinking of the RSS feeds as an alternate view of the data currently displayed.
The Version Control Subsystem
The Trac repository browser can be used to browse directories and specific revisions of files stored in the repository of the configured version control system.
Directory entries are displayed in a list with sortable columns. The list entries can be sorted by name, size or age by clicking on the column headers. The sort order can be reversed by clicking on a given column header again.
The browser can be used to navigate through the directory structure by clicking on the directory names. Clicking on a file name will show the contents of the file. Clicking on the revision number of a file or directory will take you to the TracRevisionLog for that file. Note that there's also a Revision Log navigation link that will do the same for the path currently being examined.
It's also possible to browse directories or files as they were in history, at any given repository revision. The default behavior is to display the latest revision but another revision number can easily be selected using the View revision input field at the top of the page.
(since 0.11):
At the top of the browser page, there's a drop-down menu which you can use to select some interesting places in the repository, for example branches or tags. This is sometimes referred to as the browser quickjump facility. The precise meaning and content of this menu depends on your backend. For Subversion, this list contains by default a few branches (trunk and any sub-folder of the latest branches top-level folder) and a few tags (any sub-folder of the latest tags top-level folder). This can be configured for more advanced cases.
If you're using a Javascript enabled brower, you'll be able to expand and collapse folders in-place by clicking on the arrow head at the right side of a folder. Alternatively, the keyboard can also be used for this: use 'j' and 'k' to go to the next or previous entry, and 'o' (or 'Enter') to toggle between expanded and collapsed state of the selected folder or for visiting the selected file.
For the Subversion backend, some additional features are available:
Trac has a built-in functionality for visualizing “diffs” - changes to files.
There are different kinds of change sets. Some can correspond to revisions made in the repositories, others can aggregate changes made in several revisions, but in the end, any kind of differences can be shown.
The changeset view consists of two parts, the header and the diff views.
The header shows an overview of the whole changeset. Here you will find information such as:
If more than one revision is involved in the set of changes being displayed, the Timestamp, Author and Message fields won't be shown.
In front of each listed file, you'll find a colored rectangle. The color indicates how the file is affected by the changeset.
The color legend is located below the header as a reminder.
Below the header is the main part of the changeset, the diff view. Each file is shown in a separate section, each of which will contain only the regions of the file that are affected by the changeset. There are two different styles of displaying the diffs: inline or side-by-side (you can switch between those styles using the preferences form):
In addition, various advanced options are available in the preferences form for adjusting the display of the diffs:
When viewing a repository check-in, such as when following a changeset link or a changeset event in the timeline, Trac will display the exact changes made by the check-in.
There will be also navigation links to the Previous Changeset to and Next Changeset.
Often you'll want to look at changes made on a file or on a directory spanning multiple revisions. The easiest way to get there is from the TracRevisionLog, where you can select the old and the new revisions of the file or directory, and then click the View changes button.
One of the core features of version control systems is the possibility to work simultaneously on different Lines of Developments, commonly called “branches”. Trac enables you to examine the exact differences between such branches.
Using the View changes ... button in the TracBrowser allows you to enter From: and To: path/revision pairs. The resulting set of differences consist of the changes that should be applied to the From: content in order to get to the To: content.
For convenience, it is possible to invert the roles of the old and the new path/revision pairs by clicking the Reverse Diff link on the changeset page.
The last possibility for examining changes is to use the Last Change link provided by the TracBrowser.
This link will take you to the last change that was made on that path. From there, you can use the Previous Change and Next Change links to traverse the change history of the file or directory.
When you browse the repository, it's always possible to query the Revision Log view corresponding to the path you're currently seeing. This will display a list of the most recent changesets in which the current path or any other path below it has been modified.
It's possible to set the revision at which the revision log should start, using the View log starting at field. An empty value or a value of head is taken to be the newest changeset.
It's also possible to specify the revision at which the log should stop, using the back to field. By default, it's left empty, which means the revision log will stop as soon as 100 revisions have been listed.
Also, there are three modes of operation of the revision log.
By default, the revision log stops on copy, which means that whenever an Add, Copy or Rename operation is detected, no older revision will be shown. That's very convenient when working with branches, as one only sees the history corresponding to what has been done on the branch.
It's also possible to indicate that one wants to see what happened before a Copy or Rename change, by selecting the Follow copies mode. This will cross all copies or renames changes. Each time the name of the path changes, there will be an additional indentation level. That way, the changes on the different paths are easily grouped together visually.
It's even possible to go past an Add change, in order to see if there has been a Delete change on that path, before that Add. This mode corresponds to the mode called Show only adds, moves and deletes. While quite useful at times, be aware that this operation is quite resource intensive.
Finally, there's also a checkbox Show full log messages, which controls whether the full content of the commit log message should be displayed for each change, or only a shortened version of it.
For each revision log entry, there are 7 columns shown:
The View changes... buttons (placed above and below the list of changes, on the left side) will show the set of differences corresponding to the aggregated changes starting from the old revision (first radio-button) to the new revision (second radio-button), in the TracChangeset view.
Note that the old revision doesn't need to be actually older than the new revision: it simply gives a base for the diff. It's therefore entirely possible to easily generate a reverse diff, for reverting what has been done in the given range of revisions.
Finally, if the two revisions are identical, the corresponding changeset will be shown (same effect as clicking on column 5).
At the bottom of the page, there's a ChangeLog link that will show the range of revisions as currently shown, but as a simple text, matching the usual conventions for ChangeLog files.
The revision log also provides a RSS feed to monitor the changes. To subscribe to a RSS feed for a file or directory, open its revision log in the browser and click the orange 'XML' icon at the bottom of the page. For more information on RSS support in Trac, see TracRss.
The Ticket Subsystem
The Trac ticket database provides simple but effective tracking of issues and bugs within a project.
As the central project management element of Trac, tickets are used for project tasks, feature requests, bug reports and software support issues.
As with the TracWiki, this subsystem has been designed with the goal of making user contribution and participation as simple as possible. It should be as easy as possible to report bugs, ask questions and suggest improvements.
An issue is assigned to a person who must resolve it or reassign the ticket to someone else. All tickets can be edited, annotated, assigned, prioritized and discussed at any time.
A ticket contains the following information attributes:
Note: Versions of Trac prior to 0.9 did not have the type field, but instead provided a severity field and different default values for the priority field. This change was done to simplify the ticket model by removing the somewhat blurry distinction between priority and severity. However, the old model is still available if you prefer it: just add/modify the default values of the priority and severity, and optionally hide the type field by removing all the possible values through trac-admin.
Note: the type, component, version, priority and severity fields can be managed with trac-admin or with the WebAdmin plugin.
Note: Description of the builtin priority values is available at TicketTypes
Once a ticket has been entered into Trac, you can at any time change the information by annotating the bug. This means changes and comments to the ticket are logged as a part of the ticket itself.
When viewing a ticket, the history of changes will appear below the main ticket area.
In the Trac project, we use ticket comments to discuss issues and tasks. This makes understanding the motivation behind a design- or implementation choice easier, when returning to it later.
Note: An important feature is being able to use TracLinks and WikiFormatting in ticket descriptions and comments. Use TracLinks to refer to other issues, changesets or files to make your ticket more specific and easier to understand.
Note: See TracNotification for how to configure email notifications of ticket changes.
Note: See TracWorkflow for information about the state transitions (ticket lifecycle), and how this workflow can be customized.
The option selected by default for the various drop-down fields can be set in trac.ini, in the [ticket] section:
If any of these options are omitted, the default value will either be the first in the list, or an empty value, depending on whether the field in question is required to be set.
Many of the default ticket fields can be hidden from the ticket web interface simply by removing all the possible values through trac-admin. This of course only applies to drop-down fields, such as type, priority, severity, component, version and milestone.
Trac also lets you add your own custom ticket fields. See TracTicketsCustomFields for more information.
If the list of possible ticket owners is finite, you can change the assign-to ticket field from a text input to a drop-down list. This is done by setting the restrict_owner option of the [ticket] section in trac.ini to “true”. In that case, Trac will use the list of all users who have accessed the project to populate the drop-down field.
To appear in the dropdown list, a user needs be registered with the project, i.e. a user session should exist in the database. Such an entry is automatically created in the database the first time the user submits a change in the project, for example when editing the user's details in the Settings page, or simply by authenticating if the user has a login. Also, the user must have TICKET_MODIFY permissions.
Note: See Populating Assign To Drop Down on how to add user entries at database level
Note 2: If you need serious flexibility and aren't afraid of a little plugin coding of your own, see FlexibleAssignTo (disclosure: I'm the author)
To create a link to the new-ticket form filled with preset values, you need to call the /newticket? URL with variable=value separated by &.
Possible variables are :
Example: /trac/newticket?summary=Compile%20Error&version=1.0&component=gui
The Trac reports module provides a simple, yet powerful reporting facility to present information about tickets in the Trac database.
Rather than have its own report definition format, TracReports relies on standard SQL SELECT statements for custom report definition.
Note: The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the query module is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.
You can already completely replace the reports module by the query module simply by disabling the former in trac.ini:
[components]
trac.ticket.report.* = disabled
This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.
You will almost definitely need to restart your httpd at this point.
A report consists of these basic parts:
Simple reports - ungrouped reports to be specific - can be changed to be sorted by any column simply by clicking the column header.
If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order.
There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The report table has the following schema (as of 0.10):
Changing the ID changes the shown order and number in the Available Reports list and the report's perma-link. This is done by running something like:
update report set id=5 where id=3;
Keep in mind that the integrity has to be maintained (i.e., ID has to be unique, and you don't want to exceed the max, since that's managed by SQLite someplace).
Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the Next Ticket or Previous Ticket links just below the main menu bar, or click the Back to Report link to return to the report page.
You can safely edit any of the tickets and continue to navigate through the results using the Next/Previous/Back to Report links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets). (since 0.11)
Aside from the default HTML view, reports can also be exported in a number of alternative formats. At the bottom of the report page, you will find a list of available data formats. Click the desired link to download the alternative report format.
Export the report as plain text, each row on its own line, columns separated by a single comma (','). Note: Carriage returns, line feeds, and commas are stripped from column data to preserve the CSV structure.
Like above, but uses tabs (\t) instead of comma.
All reports support syndication using XML/RSS 2.0. To subscribe to an RSS feed, click the orange 'XML' icon at the bottom of the page. See TracRss for general information on RSS support in Trac.
Creating a custom report requires a comfortable knowledge of SQL.
A report is basically a single named SQL query, executed and presented by Trac. Reports can be viewed and created from a custom SQL expression directly in from the web interface.
Typically, a report consists of a SELECT-expression from the 'ticket' table, using the available columns and sorting the way you want it.
The ticket table has the following columns:
See TracTickets for a detailed description of the column fields.
all active tickets, sorted by priority and time
Example: All active tickets, sorted by priority and time
SELECT id AS ticket, status, severity, priority, owner,
time as created, summary FROM ticket
WHERE status IN ('new', 'assigned', 'reopened')
ORDER BY priority, time
For more flexible reports, Trac supports the use of dynamic variables in report SQL statements. In short, dynamic variables are special strings that are replaced by custom data before query execution.
The syntax for dynamic variables is simple, any upper case word beginning with '$' is considered a variable.
Example:
SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
To assign a value to $PRIORITY when viewing the report, you must define it as an argument in the report URL, leaving out the leading '$'.
Example:
http://trac.edgewall.org/reports/14?PRIORITY=high
To use multiple variables, separate them with an '&'.
Example:
http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical
There is one magic dynamic variable to allow practical reports, its value automatically set without having to change the URL.
Example (List all tickets assigned to me):
SELECT id AS ticket,summary FROM ticket WHERE owner=$USER
Trac is also capable of more advanced reports, including custom layouts, result grouping and user-defined CSS styles. To create such reports, we'll use specialized SQL statements to control the output of the Trac report engine.
To format reports, TracReports looks for 'magic' column names in the query result. These 'magic' names are processed and affect the layout and style of the final report.
Example:
SELECT id as ticket, created, status, summary FROM ticket
Columns whose names begin and end with 2 underscores (Example: __color__) are assumed to be formatting hints, affecting the appearance of the row.
Defaults: Color 1 Color 2 Color 3 Color 4 Color 5
Example: List active tickets, grouped by milestone, colored by priority
SELECT p.value AS __color__,
t.milestone AS __group__,
(CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
t.id AS ticket, summary
FROM ticket t,enum p
WHERE t.status IN ('new', 'assigned', 'reopened')
AND p.name=t.priority AND p.type='priority'
ORDER BY t.milestone, p.value, t.severity, t.time
Note: A table join is used to match ticket priorities with their numeric representation from the enum table.
By default, all columns on each row are display on a single row in the HTML report, possibly formatted according to the descriptions above. However, it's also possible to create multi-line report entries.
Example: List active tickets, grouped by milestone, colored by priority, with description and multi-line layout
SELECT p.value AS __color__,
t.milestone AS __group__,
(CASE owner
WHEN 'daniel' THEN 'font-weight: bold; background: red;'
ELSE '' END) AS __style__,
t.id AS ticket, summary AS summary_, -- ## Break line here
component,version, severity, milestone, status, owner,
time AS created, changetime AS modified, -- ## Dates are formatted
description AS _description_, -- ## Uses a full row
changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
FROM ticket t,enum p
WHERE t.status IN ('new', 'assigned', 'reopened')
AND p.name=t.priority AND p.type='priority'
ORDER BY t.milestone, p.value, t.severity, t.time
If you have added custom fields to your tickets (a feature since v0.8, see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.
If you have tickets in the database before you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See TracIniReportCustomFieldSample for some examples.
Note that you need to set up permissions in order to see the buttons for adding or editing reports.
In addition to reports, Trac provides support for custom ticket queries, used to display lists of tickets meeting a specified set of criteria.
To configure and execute a custom query, switch to the View Tickets module from the navigation bar, and select the Custom Query link.
When you first go to the query page the default filters will display all open tickets, or if you're logged in it will display open tickets assigned to you. Current filters can be removed by clicking the button to the right with the minus sign on the label. New filters are added from the pulldown list in the bottom-right corner of the filters box. Filters with either a text box or a pulldown menu of options can be added multiple times to perform an or of the criteria.
You can use the fields just below the filters box to group the results based on a field, or display the full description for each ticket.
Once you've edited your filters click the Update button to refresh your results.
Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the Next Ticket or Previous Ticket links just below the main menu bar, or click the Back to Query link to return to the query page.
You can safely edit any of the tickets and continue to navigate through the results using the Next/Previous/Back to Query links after saving your results. When you return to the query any tickets which were edited will be displayed with italicized text. If one of the tickets was edited such that it no longer matches the query criteria the text will also be greyed. Lastly, if a new ticket matching the query criteria has been created, it will be shown in bold.
The query results can be refreshed and cleared of these status indicators by clicking the Update button again.
While Trac does not yet allow saving a named query and somehow making it available in a navigable list, you can save references to queries in Wiki content, as described below.
You may want to save some queries so that you can come back to them later. You can do this by making a link to the query from any Wiki page.
[query:status=new|assigned|reopened&version=1.0 Active tickets against 1.0]
Which is displayed as:
Active tickets against 1.0
This uses a very simple query language to specify the criteria (see Query Language).
Alternatively, you can copy the query string of a query and paste that into the Wiki link, including the leading ? character:
[query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner]
Which is displayed as:
Assigned tickets by owner
The TicketQuery macro lets you display lists of tickets matching certain criteria anywhere you can use WikiFormatting.
Example:
[[TicketQuery(version=0.6|0.7&resolution=duplicate)]]
This is displayed as:
#181
Wiki preview injects new lines
#204
request for colour legend (or something similar) for ticket groups in reports
#226
Ticket Dependencies
#239
Link to diff of specifik wiki change instead of the page itself
#351
All ticket modifications should be tracked in timeline
#413
Installing on Windows, drive other than C:
#450
Diffviewer should try to convert the text into utf-8.
#475
merging of similar tickets
#519
Python process sometimes hangs on Windows Server 2003
#529
IE 5-6 over HTTPS broken downloads
Just like the query: wiki links, the parameter of this macro expects a query string formatted according to the rules of the simple ticket query language.
A more compact representation without the ticket summaries is also available:
[[TicketQuery(version=0.6|0.7&resolution=duplicate, compact)]]
This is displayed as:
#181#204#226#239#351#413#450#475#519#529
Finally if you wish to receive only the number of defects that match the query using the count parameter.
[[TicketQuery(version=0.6|0.7&resolution=duplicate, count)]]
This is displayed as:
10
You can also customize the columns displayed in the table format (format=table) by using col=<field> - you can specify multiple fields and what order they are displayed by placing pipes (|) between the columns like below:
[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter)]]
This is displayed as:
| Ticket | Resolution | Summary | Owner | Reporter |
| invalid | ZipImportError: bad local file header in /usr/lib/python2.5/site-packages/TracScreenshots-0.7-py2.5.egg | socksys | ||
| invalid | (only windows 7 Beta1 ) Unable to use DOS software because it is too slow | anonymous | ||
| wontfix | OperationalError: database is locked | gkruse@… |
query: TracLinks and the [[TicketQuery]] macro both use a mini “query language” for specifying query filters. Basically, the filters are separated by ampersands (&). Each filter then consists of the ticket field name, an operator, and one or more values. More than one value are separated by a pipe (|), meaning that the filter matches any of the values.
The available operators are:
|
All of these operators can also be negated:
|
The roadmap provides a view on the ticket system that helps planning and managing the future development of a project.
Basically, the roadmap is just a list of future milestones. You can add a description to milestones (using WikiFormatting) describing main objectives, for example. In addition, tickets targeted for a milestone are aggregated, and the ratio between active and resolved tickets is displayed as a milestone progress bar.
It is possible to drill down into this simple statistic by viewing the individual milestone pages. By default, the active/resolved ratio will be grouped and displayed by component. You can also regroup the status by other criteria, such as ticket owner or severity. Ticket numbers are linked to custom queries listing corresponding tickets.
It is possible to add, modify and remove milestones using either TracAdmin or the web interface.
Note: Milestone descriptions can currently only be edited from the web interface. With appropriate permissions, you'll see buttons for milestone management on the roadmap and milestone pages.
The Roadmap supports the iCalendar format to keep track of planned milestones and related tickets from your favorite calendar software. Calendar applications supporting the iCalendar specification include Apple iCal for Mac OS X and the cross-platform Mozilla Calendar, and Chandler. Korganizer (the calendar application of the KDE project) and Evolution also support iCalendar.
To subscribe to the roadmap, copy the iCalendar link from the roadmap (found at the bottom of the page) and choose the "Subscribe to remote calendar" action (or similar) of your calendar application, and insert the URL just copied.
Note: For tickets to be included in the calendar as tasks, you need to be logged in when copying the link. You will only see tickets assigned to yourself, and associated with a milestone. More information about iCalendar can be found at Wikipedia.
Here you can find answers to some of the most 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.
Where do I find the two-page summary on what Trac and its features are? I'm looking for some kind of documentation that I can show my boss, so that he'll get interested enough to allow me to spend the time and resources to test-install and evaluate further.
There's a WIP list on TracFeatures. Please help expand it.
Trac will run on any system supported by Python and the depending modules. Today we are aware of people running Trac on various Linux distributions, Mac OS X, FreeBSD, NetBSD and MS Windows.
See also: TracOnFreeBsd , TracOnNetBsd , TracOnOsx, TracOnMandrakelinux, TracOnGentoo, TracOnDebian, TracOnFedoraCore, TracOnRedhat, TracOnWindows, TracOnSLES9 ... and various others, listed in TracInstallPlatforms.
Starting with version 0.9, Trac is released under the modified BSD license. Versions of Trac prior to 0.9 were released under the GNU General Public License (GPL).
There is a script to assist with the migration at source:trunk/contrib/bugzilla2trac.py For more information see: TracImport
./setup.py install --prefix=/my/directory/for/trac
Yes, PostgreSQL since 0.9 and MySQL since 0.10.
See also: DatabaseBackend.
(or do I have to setup a different directory for each one?)
Only one installation is required, then for each project create an Environment (using trac-admin <fooproj> initenv). They will be separate projects, all handled by the same installation of Trac.
Note: Right now there is no support for sharing information between projects.
The rationale for this is that the scope of Trac (1.0) is to manage a single project, and do it well. Support for larger multi-project management adds a lot of complexity, but is planned for post-1.0 development, probably as a separate framework around Trac.
See also: TracMultipleProjects
If you are serving Trac with Apache, you can use the following directives to let your users access Trac with URLs like "http://www.example.com/trac/" rather than the default "http://www.example.com/cgi-bin/trac.cgi". This example shows how to set it up for Apache 2 on a Windows server, but it works just as well with Apache 1.3 or on Unix.
# Map the Trac CGI into /trac/
ScriptAliasMatch ^/trac(.*) "C:/Program Files/Apache Group/Apache2/cgi-bin/trac.cgi$1"
# Tell Trac where its environment is stored
<Location "/trac">
SetEnv TRAC_ENV "C:/Subversion/trac/CogTool.db"
</Location>
# Authenticate the user
<Location "/trac/login">
AuthType Basic
AuthName "Trac"
AuthUserFile C:/Subversion/Repo/svn-users
Require valid-user
</Location>
# Link the static files into /trac-static/
# You'll need to change the trac.ini to point to /trac-static/ instead of /trac/
Alias /trac-static/ "C:/Subversion/trac/htdocs/"
# Allow access to the Trac static files
<Directory "C:/Subversion/trac/htdocs">
AllowOverride None
Order allow,deny
Allow from all
</Directory>
See also: TracPrettyUrls
Note: The ScriptAliasMatch on /trac.. masks the Alias /trac-static/, so this didn't worked well form me. Instead I used the alias /static-trac/.
The templates are stored here
$PYTHON_HOME/share/trac
miscellaneous resources, including:
$TRAC_ENV/conf/trac.ini
settings, including (but not limited to):
See also: TracInterfaceCustomization#SiteAppearance
With the TracAdmin command hotcopy. See TracBackup for documentation.
You can't use Trac (not yet) with remote repository but you could mirror remote repository using this program: http://svk.elixus.org/
If you are using subversion 1.4, svnsync program also help you to mirror repository across network.
If you're on Windows, the Python bindings support UNC paths, so you can use a repository that's shared out on another machine. Just use the UNC path instead of the local file path when setting up Trac. (Note that this can be slow and that this usage is not recommended by the Subversion development team.)
See also: #493, VersioningSystemBackend.
You change the format by setting an appropriate 'locale' in the configuration of your webserver. You do this for Apache by adding
SetEnv LC_TIME "xx_YY"
Right after the line where you set TRAC_ENV.
For Lighttpd you do this by adding the following to the bin-environment:
"LC_TIME" => "xx_YY"
On a Linux/Un*x platform:
xx
The language code as defined in ISO 639
YY
The upper case, two letter country code as defined in ISO 3166
Examples: de_DE is Germany, en_GB is Great Britain and fr_FR is France For ending up with a ISO 8601 style, you could use en_DK or ro_RO.
On a Windows platform:
xx
The language name as defined in ISO 639
YY
The country name as defined in ISO 3166
Examples: German_Germany is Germany, English_United Kingdom is Great Britain and French_France is France
When it does not work
First, you should check, if the chosen locale is installed on the system at all.
On Linux, you can use
localedef --list-archive
or
On FreeBSD you can use
locale -a
to list the installed locale definitions.
If this is not the problem, then LC_TIME may be overridden by LC_ALL or LANGUAGE defined in the system environment. You may try one of them (LANGUAGE has highest priority) instead LC_TIME. Note that LC_TIME just affects the date and time display, whereas LC_ALL and LANGUAGE also affect handling of system messages, sorting and other country dependent output/input. So the conservative way is to stick to LC_TIME if possible. On RedHat change /etc/sysconfig/httpd and set
HTTPD_LANG=xx_YY
On Debian, edit /etc/init.d/apache2 and add LC_TIME=xx_YY to the ENV variable. Run dpkg-reconfigure locales as root if the locale you require is not available.
Changing the date and time format with mod_python
To change the date and time format when using mod_python you should instead use 'PythonOption' to set the 'TracLocale'. So for a Un*x-like system, simply do this...
<Location /projects>
SetHandler mod_python
PythonOption TracLocale "de_DE.UTF-8"
...
</Location>
or on a Windows system:
<Location /projects>
SetHandler mod_python
PythonOption TracLocale "English_United Kingdom"
...
</Location>
Make sure you install the Python bindings of Subversion, just having Subversion is not good enough.
The error reported by Trac will look something like this:
Indexing repository
Failed to initialize environment. No module named svn
Traceback (most recent call last):
File "/usr/lib/python2.3/site-packages/trac/scripts/admin.py", line 616, in do_initenv repos = self.__env.get_repository()
File "/usr/lib/python2.3/site-packages/trac/env.py", line 155, in get_repository from trac.versioncontrol.svn_fs import SubversionRepository
File "/usr/lib/python2.3/site-packages/trac/versioncontrol/svn_fs.py", line 25, in ? from svn import fs, repos, core, delta
ImportError: No module named svn
Note that in recent versions of Trac, this error reads rather: TracError: Unsupported version control system "svn". .
To verify you should have a libsvn and svn directory underneath Python's site-packages directory, but see rather TracSubversion#unsupported-vcs for more detailed troubleshooting information.
If you do not have this use something like the following to fix this:
On Gentoo Linux:
USE="python" emerge subversion
On FreeBSD use the ports/devel/subversion-python port (preferred way) or ports/devel/subversion with
WITH_PYTHON=true
When using pkgsrc, please make sure to use the pkgsrc/devel/py-subversion pkg.
(this has been confirmed with Trac version 0.9-1 on Ubuntu 5.10 (Breezy Badger))
Check your version of Silvercity. If you are using version 0.9.6 of Silvercity which was released on 2005/12/30 you will see an error in your trac.log file (assuming you have logging turned on) that looks like this:
09:00:33 Trac[api] DEBUG: Trying to render HTML preview using SilverCityRenderer
09:00:33 Trac[api] WARNING: HTML preview using <trac.mimeview.silvercity.SilverCityRenderer object at 0xb6dd4d8c> failed
(expected sequence of 3 WordLists (2 provided))
Traceback (most recent call last):
File "/usr/lib/python2.4/site-packages/trac/mimeview/api.py", line 232, in render result = renderer.render(req, mimetype, content, filename, rev)
File "/usr/lib/python2.4/site-packages/trac/mimeview/silvercity.py", line 98, in render generator().generate_html(buf, content)
File "/usr/lib/python2.4/site-packages/SilverCity/CSS.py", line 32, in generate_html lexer.tokenize_by_style(buffer, self.event_handler)
File "/usr/lib/python2.4/site-packages/SilverCity/Lexer.py", line 8, in tokenize_by_style call_back
TypeError: expected sequence of 3 WordLists (2 provided)
Steps to fix:
CSS highlighting should now work!
If you turn on full logging, you might see this error in your trac.log file:
WARNING: HTML preview using <trac.mimeview.php.PHPRenderer object at 0xb7b6032c> failed (You appear to be using the PHP CGI binary. Trac requires the CLI version for syntax highlighting.)
Steps to fix:
- [mimeviewer]
- php_path = c:\PHP\php.exe
- [mimeviewer]
- php_path = /usr/local/bin/php
When setting up your Trac environment simply append the subtree of interest to the repository path, eg, if your repository resides in '/var/svn' and you only want to handle a project '/myproject' in Trac, you'd specify '/var/svn/myproject' as your repository path. Alternatively you can change the path in the 'repository_dir' setting in your 'conf/trac.ini' inside the trac instance directory.
Sort of, since version 0.11. See TracIni#svn:externals-section.
See also TracFaq#can-i-use-trac-with-a-remote-subversion-repository
Not currently, but this issue (#1024) is a planned feature for the 0.13 release.
Yes, you want to have a look at the WebAdmin plugin. Note however that:
Despite its name, the "Fast CGI" solution is often quite a bit slower than mod_python or mod_wsgi. Try the TracModPython or TracModWSGI installation. Changing from fcgi to mod_python/mod_wsgi can easily give an order of magnitude (n*10) increase in performance.
Start by reading the TracSubversion page and its troubleshooting section.
In particular, there are detailed instructions for how to deal with very common installation issues, like the Unsupported version control system "svn" error or the RuntimeError: instance.__dict__ not accessible in restricted mode ones.
Start by reading the PySqlite page and its troubleshooting section.
Start by reading the TracModPython page and its troubleshooting section.
On occasion, you may bump into the following error:
UnicodeDecodeError: 'utf8' codec can't decode byte 0xXX in position i: unexpected code byte
This error usually shows up after one of the following events occurred:
See TracUnicode to find out how to convert a database archive.
... check the TracTroubleshooting page, which contains general advices about how to figure out what's really going on.
Before trying to log in, an authentication mechanism (outside of Trac) has to be set-up. See:
Internet explorer is not too keen on obeying rules. Try to add this line in your httpd.conf:
SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
See also: http://www.modssl.org/docs/2.7/ssl_faq.html#ToC48
It's possible you have two versions of trac active at the same time. See the comments on ticket #3915
It's possible you have two versions of trac active at the same time. See the comments on ticket #3915
The term Wiki is a shortened form of WikiWikiWeb. A Wiki is a database of pages that can be collaboratively edited using a web browser.
See also: TracWiki
Why yes, thanks for asking.
Just access the URL http://yourhost/trac/wiki/newpage and click on the "Edit This page link"
Good "wiki" style suggests however that you start by editing some existing page, then insert a WikiPageName and save the page. The WikiPageName link will be displayed as a missing link (i.e. LikeThat?), and by following this link, you end up on the page creation interface. By following this practice, you tend to avoid OrphanedPages.
See also: WikiNewPage
Users with the WIKI_DELETE permission can click the "Delete Page" button at the bottom of the page.
The TracAdmin utility can also remove Wiki pages like so:
trac-admin <yourprojenv> wiki remove PageName
Yes, Trac uses UTF-8 internally for all text. See TracUnicode for a detailed description.
Make a wiki link that looks like [file:///%5C%5Cserver/path/to/file/readme.txt Readme]. In Mozilla or Firefox type about:config in your browser window and change security.checkloaduri to false. More info: http://tinyurl.com/4xg9c
Currently you can use a 3rd party MacroBazaar#BackLinks WikiMacro to do this
There is also ticket #611 requesting this feature in Trac.
Users with WIKI_DELETE permissions can delete attachments. To do this, login as the privileged user, click on the attachment. The attachment page will now have a "Delete Attachment" button you can use to delete the attachment. Note that is an irreversible operation.
Could I download attached file, update it and upload it back with same name? See related #948.
You can use the attachment:wiki:TracWiki:mediawiki2trac.py script as a starting point. WikiProcessor for the MediaWiki styles has been started as trac plugin on http://trac-hacks.org/wiki/MediaWikiPluginMacro.
Yes, you can! However, please don't add unanswered questions, only topics that you've regularly answered yourself or issues you're familiar with. Good places to ask questions are the MailingList and the IrcChannel.
Just click Edit this page at the bottom of the page.
Please note that this page is no longer written using reStructuredText... Thanks to the [[PageOutline]] macro, the index for this FAQ is generated automatically.
I guess you would get an answer rapidly if you added a malicious contribution, and you just might get a bruise (and we'll send you an ICE).
trac-admin in trac 0.8 and above has a built-in command to resync the repository that works like this.
trac-admin <yourprojenv> resync
Note: this problem concerns old version of Subversion and Trac, and can probably be deleted from the FAQ. The tree diff functionality provided by the subversion python bindings use an external diff_ command. On UNIX-like systems, diff is usually installed already, so this wasn't an issue there. Installing diffutils should solve the problem.
After installing diffutils, you will need to add the path to the diff executable to the Windows PATH environment variable and reboot the machine.
Yes, using several methods. See TracSyntaxColoring for details.
Yes, using TracAdmin (in milestone:0.10 or later?):
trac-admin <yourprojenv> ticket remove <num>
You have to go through the db file in order to remove a ticket. For a web interface, see TracHacks:TicketDeletePlugin.
You can replace the free text box with a drop-down list of known users to assign ticket owners: See TracTickets#Assign-toasDrop-DownList.
For example, is it possible to import and export in the same way as one can using trac-admin for the wiki?
NOTE: For Trac 0.10 and above, you can use the Datamover plugin to do this.
A possible approach (until someone comes up with a better one?!) is to use the sqlite engine to export the tickets and changes, generate a script, and then insert the records into the second trac installation. E.g.:
[root@xgbemf6002 root]# sqlite <path/to/trac_project/db/trac.db>
SQLite version 2.8.15
Enter ".help" for instructions
sqlite> .output ticket.sql
sqlite> .dump ticket
Outputs the table, both the schema and the data, into the file ticket.sql. You can then import this file into your new installation by doing something like sqlite < ticket.sql. You will need to either drop the ticket table in your new installation or remove the "create table" statement out of the ticket.sql file.
As provided below, the database schema can be found here
Moving from Win2k, SQLite 3 to Debian 3.1, SQLite 2 the following worked:
sqlite3.exe e:\\project\\db\\trac.db .dump > c:\\project.sql
copy this file and any attachments/templates to the new server.
sqlite /new/project/db/trac.db
.read project.sql
.exit
Move the other files into position. Done!
In version 0.9 Trac will use the email address from the Settings page for authenticated users.
Yes, you can setup Subversion to update the Trac ticket when you commit changes with a message listing tickets that are fixed or related. You can read the comments in the beginning of the file contrib/trac-post-commit-hook source:/trunk/contrib/trac-post-commit-hook for more information on how to set this up.
If you are using a stable version rather than the latest development version you should instead get the script which matches your release - for example source:/branches/0.9-stable/contrib/trac-post-commit-hook (if you build from source, you will find the correct script version in your trac-xxx/contrib folder)
If the trac-post-commit-hook script does not appear to be working, for some extra clues try running it from the command-line using the account normally used to run it and without an environment (as it's normally executed). Change to the relevant user and execute the following from the subversion repository hooks directory:
env - ./post-commit /svn/test 7
This will also check your subversion hook is calling trac-post-commit-hook.
If the results give you something like this:
"ImportError: no module named trac.env"
then it's likely python has not been found properly by line 1 of trac-post-commit-hook, so change line 1 to suit your system, such as:
#!/usr/local/bin/python
If it runs manually but not from Subversion, make sure first line in script post-commit (for linux) is #!/bin/sh (does not show in example script).
Disable the ticket components, in your TracIni:
[components]
trac.ticket.* = disabled
Also, it's quite simple to write a plugin to redirect ticket references to your legacy ticket system: e.g. mantis_tickets.py (replacement for all bug links with disabled tickets) or mantis_tickets_link.py (parses "Mantis #xxxxxx" links only).
Outlook can be configured to use a monospace font by going to Tools -> Options... -> Email format -> Fonts ... -> International Fonts. Highlight Unicode in the language list, select Courier New as the proportional font, and select Unicode (UTF-8) as encoding.
Or try http://outlooktrac.googlepages.com/ - utility to sync trac tickets with outlook.
Yes, if you have the proper permissions, you should be able to delete a report simply by viewing it and clicking Delete.
There are several ways to contribute, including submitting patches, sending feedback and reporting bugs. For details, see HowToContribute. For development specific documentation, see TracDev.
Yes and no. Merely translating the templates is not enough to provide complete internationalization of Trac. Python supports gettext just fine, but templates might require some extra work.
The standpoint of the TracTeam right now is to postpone translation efforts until the feature base and source code has stabilized somewhat, so as to not add too much extra work until 1.0.
That said, people have already started looking into it, and making some good suggestions already. We will need help with translation efforts. If you're interested in volunteering, please consider joining the mailing list.
For more information refer to TracL10N
See TracDev/DatabaseSchema.
In Trac 0.8.x and below the schema is available in source:branches/0.8-stable/trac/db_default.py
Trac no longer has the schema in plain SQL since it was necessary to abstract the table creation in order to support other database platforms. However, the structure in db_default.py still provides a representation of the schema.
To get a definitive schema for your install:
prompt> sqlite3 /path/to/tracdata/yourinstance/db/trac.db
sqlite> .schema
Some users prefer to use Trac as an issue-tracker and Wiki and thus don't require the version control subsystem. When initializing a project's environment with trac-admin, don't enter anything for the repository directory (i.e. keep the default). Then add the following to project/conf/trac.ini:
[components]
trac.versioncontrol.* = disabled
Using trac-admin, specifically the milestone time or milestone add command. The input format for the date is rather limited still, and should be a string like this: 'Jun 3, 2003'. Note the string must be quoted for proper parsing. Example:
trac-admin myprojenv milestone add anniversary 'Jun 3, 2003'
Currently only Subversion is supported, but Trac will probably support other systems in the future. See discussion of this on VersioningSystemBackend.
Also, CVSTrac is a similar, but far simpler system which can track a CVS repository
Apache supports LDAP authentication with mod_auth_ldap. You can use this in place of the other authenticate methods used in the installation guides. It may be easier, however, depending on your installation, to use mod_auth_pam with Apache and configure PAM to use LDAP for authentication.
You can use LDAP to manage your Trac groups and permissions with the TracHacks:LdapPlugin.
All Rights Reserved Powered by 文档下载网
Copyright © 2011