Moving to setuptools

DONE This proposal has been integrated for the 0.11 release.

This page describes the plan to move to the ​setuptools package for deploying Trac.

Benefits

Adopting setuptools brings a number of benefits, mostly centered around making installation easier and the plugin system more robust.

• Trac will become better suited to be installed using ​EasyInstall, including automatic downloading and installation of dependencies such as Genshi.
• Programs such as trac-admin and tracd will be installed as wrapper scripts suitable to the installation platform. For example, on Windows the programs will be installed as executables (.exe), making them easier to invoke from the command prompt.
• Plugins will be able to declare compatibility with a specific version of Trac. Thus you could have a plugin that says it requires e.g. "Trac>=0.11.3." (see ​declaring dependencies).
• We will be able to provide a common package namespace (called tracext) that third-party developers could use for their plugin code, meaning the Python package namespace won't get polluted by those plugins.
• The listing of Trac modules in at the bottom of db_default.py​ will be replaced by entry points declared in the setup.py file, and thus registered using the same mechanism already in use by external plugins.
• Optionally, we could support the entry point for WSGI app factories exposed by ​Paste Deploy.

Required Changes

Some aspects of how Trac is currently packaged and run need to be changed so that it can be deployed with setuptools.

siteconfig

The module trac.siteconfig, which is currently generated at installation time, will be removed. Its purpose was to tell Trac where to find various installation-wide directories and files such as

• templates,
• static resources (htdocs),
• default wiki pages,
• plugins,
• the configuration file

The templates, static resources, and the default set of wiki pages will become ​package data, meaning they will be installed alongside the application code, and no longer intended to be modified by the site admin. Instead they should be overridden using a site template and a site-specific CSS stylesheet.

The other cases are mostly interesting for deployments handling multiple projects, where every project should inherit some aspects from a shared location. This scenario will be handled by allowing trac.ini to inherit configuration values from an explicitly specified “parent” configuration. For example, the trac.ini file of an environment might start like this:

[inherit]
file = /etc/trac.ini

The inherited configuration file could then specify global directories for the templates, plugins, and default wiki pages, in addition to most other options already usable with the global trac.ini file.

This approach is both more explicit and more flexible than the current model. For example, it allows multiple inheritance levels, as opposed to the fixed global→environment levels we currently provide.

Environment Initialization

As the location of the global configuration file will no longer be available implicitly, trac-admin will need to be modified so that this information can be passed to it using command-line options and/or environment variables.

For example:

$ trac-admin --inherit-file=/etc/trac.ini /var/trac/myproj initenv

or:

$ export TRAC_CONFIG=/etc/trac.ini
$ trac-admin /var/trac/myproj initenv

I'd like to combine this with making trac-admin make use of options instead of positional arguments for the initenv command, so that even a simple invocation as above would just create the environment, instead of prompting for information that can easily be provided later.

Open Questions

When moving the templates and htdocs into package data, should we try and split them up for the different subsystems? I.e. should all the ticket system templates live under trac/ticket/templates, or together with all other templates in trac/templates?

Personally, I'd prefer splitting them up. — ChristopherLenz
me too — ChristianBoos

The [inherit] mechanism is quite flexible (ability to specify the various locations for everything), but there should probably be a way to specify one location where to look for all the various parts (could be the parent directory containing all the various package data, and expecting an htdocs subfolders, a templates subfolder, etc.).

see #3897 and ​PlanEnvInheritance — ilias@…

Status

The sandbox/setuptools@4821 branch contains most of the changes described, but is based on a rather old version of trunk. Because this proposal requires moving many files around (causing pain when merging), I would prefer doing these changes in one big changeset directly on trunk instead of updating the branch.

You can view the diff to get a feeling for the changes required.

---

See also: ​Thread on trac-dev, Milestone 0.11, TracDev/Proposals