Supported options
=================

The recipe supports the following options:

``project-name`` (required)

  Name of the Trac instance. This name will also be used as the default value
  for the ``smtp-from-name`` option. Default value: ``My project``.

``project-description``

  Description of the project. This description will also be used as the
  alternative text to the header logo.

``project-url``

  This URL will be used as the link on the header logo. Default value:
  ``http://example.com``.

``repos`` (required)

  This parameter list all the code repositories managed by your Trac instance.
  The syntax must respect the following scheme: ``Name | Type | Path | URL``.
  Name must be alphanumerical lower string. Supported values for types are:
  ``svn`` for Subversion, ``hg`` for Mercurial. Path must point to the location
  of your code repository in the file system. The URL is not mandatory.
  You can add several repositories, one per line. Example::

    repos = repo1 | svn | /data/svn/my_reposo                        | http://my-domain.net/subversion/repo1
            repo2 | svn | ${buildout:directory}/repos/another_reposo | svn://example.com/repo2
            repo3 | hg  | /data/hg/reposo2                           | https://user@stuff.com/project

``default-repo``

  If set with a repository name, this will create an alias from the default
  repository to the given repository. Example::

    default-repo = repo2

``repos-sync``

  This option deals with the way repositories are synchronized with Trac.

  Currently it only support `per-request synchronization
  <http://trac.edgewall.org/wiki/TracRepositoryAdmin#Synchronization>`_. This is
  the method that will be setup if you give this option the ``request`` value.
  This is the default value.

  In the future, this option will accept ``hook`` as a value, to setup `explicit
  synchronization
  <http://trac.edgewall.org/wiki/TracRepositoryAdmin#ExplicitSync>`_.

  This option only takes Subversion repositories into account.

``force-instance-upgrade``

  If set to ``True``, this will trigger the internal Trac upgrade process on
  the current instance, even if Trac don't think it's needed. Default value:
  ``False``.

``force-repos-resync``

  If set to ``True``, this will force the resynchronization of Trac against all
  the repositories. Default value: ``False``.

``wiki-doc-upgrade``

  If set to ``True``, this will upgrade the default wiki pages embedded in the
  current Trac instance. As said in Trac documentation, this `will not remove
  deprecated wiki pages
  <http://trac.edgewall.org/wiki/TracUpgrade#WikiUpgrade>`_ that were previously
  part of a Trac release. Default value: ``False``.

``remove-examples``

  If set to ``False``, this will not remove the default milestones and
  components added by Trac when creating a brand new instance. Default value:
  ``True``.

``milestones``

  List of all custom milestones to create. You can add several custom
  parameters, one per line. Example::

    milestones = 0.1
                 0.2
                 1.0
                 Future
                 Undecided

``components``

  List of components for which we can attached Trac tickets to. The syntax must
  follow the ``Component name | Component owner`` scheme, but components without
  an owner are allowed. Example::

    components = The application itself | kevin
                 Project web site
                 Build tools            | cecile

``permissions``

  List of custom permissions to set. Both users and groups are supported.
  Example::

    permissions = cecile        | REPORT_ADMIN
                  kevin         | PERMISSION_ADMIN MILESTONE_ADMIN REPORT_ADMIN
                  anonymous     | STATS_VIEW
                  authenticated | REPORT_MODIFY MILESTONE_MODIFY

  A `list of permissions <http://trac.edgewall.org/wiki/TracPermissions>`_ can
  be found on Trac's wiki. In respects to Trac's conventions, all permissions
  are automatically upper-cased by the recipe.

``header-logo``

  Location of the logo that will replace the default Trac logo at the top of
  each page. The file will be copied by the recipe to the ``htdocs`` directory
  of your Trac instance.

``footer-message``

  The bottom right-aligned text displayed on each page displayed by Trac. HTML
  can be used here. Default value ``This Trac instance was generated by
  <a href="http://pypi.python.org/pypi/pbp.recipe.trac">pbp.recipe.trac</a>.``.

``smtp-always-bcc``

  Email address(es) to always send notifications to, addresses do not appear
  publicly (Bcc:).

``smtp-always-cc``

  Email address(es) to always send notifications to, addresses can be seen by
  all recipients (Cc:).

``smtp-default-domain``

  Default host/domain to append to address that do not specify one

``smtp-enabled``

  Enable SMTP (email) notification.

``smtp-from``

  Sender address to use in notification emails.

``smtp-from-name``

  Sender name to use in notification emails. Default value: ``project-name``
  option value.

``smtp-password``

  Password for SMTP server.

``smtp-port``

  SMTP server port to use for email notification.

``smtp-replyto``

  Reply-To address to use in notification emails.

``smtp-server``

  SMTP server hostname to use for email notifications.

``smtp-subject-prefix``

  Text to prepend to subject line of notification emails. If the setting is not
  defined, then the value of ``project-name`` is used as prefix. If no prefix
  is desired,then specifying an empty option will disable it.

``smtp-user``

  Username for SMTP server.

``additional-menu-items``

  This will use the `NavAdd plugin <http://trac-hacks.org/wiki/NavAddPlugin>`_
  to add new menu entries in Trac's top navigation toolbar. The syntax must
  respect the following scheme: ``Title | Url``. You can specify multiple menu
  entries as shown in the following example::

    additional-menu-items = Buildbot      | http://localhost:9080/
                            Demo instance | http://trac.edgewall.org/demo-0.13

``time-tracking-plugin``

  If set to ``enabled``, will activate the `Estimation and Time Tracking plugin
  <http://trac-hacks.org/wiki/TimingAndEstimationPlugin>`_. Default value:
  ``disabled``.

``stats-plugin``

  If set to ``enabled``, will activate the `TracStats plugin
  <http://trac-hacks.org/wiki/TracStatsPlugin>`_. Default value: ``disabled``.

``trac-ini-additional``

  In case a Trac parameter is not natively supported by this recipe, you can
  use this to add your own. The syntax must respect the following scheme:
  ``Section | Parameter | Value``. You can add several custom parameters, one
  per line. Example::

    trac-ini-additional = attachment   | max_size            | 52428800
                          notification | always_notify_owner | true
                          logging      | log_level           | DEBUG

  This option is applied just before writing the final ``trac.ini`` generated by
  this recipe. So thanks to ``trac-ini-additional``, you always have a way to
  fix your ``trac.ini`` even if this recipe breaks it.

  And to get more informations on all the ``trac.ini`` parameters, see:
  http://trac.edgewall.org/wiki/TracIni


Example usage
=============

We'll start by creating a buildout that uses the recipe::

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = trac
    ... index = http://pypi.python.org/simple
    ...
    ... [trac]
    ... recipe = pbp.recipe.trac
    ... project-name = My project
    ... project-url = http://example.com
    ... repos = repo1 | hg | sqlite:${buildout:directory}/var/svn | http://my-domain.net/subversion/repo1
    ... default-repo = repo1
    ... header-logo = ${buildout:directory}/my_logo
    ... smtp-server = localhost
    ... smtp-port = 25
    ... smtp-from = tarek@ziade.org
    ... smtp-replyto = tarek@ziade.org
    ... milestones = 0.1
    ...              0.2
    ...              1.0
    ...              Future
    ...              Undecided
    ... components = The application itself | kevin
    ...              Project web site
    ...              Build tools            | cecile
    ... """)

Let's run the buildout::

    >>> res = system(buildout)

This creates a trac instance::

    >>> ls(join(sample_buildout, 'parts', 'trac'))
    -  README
    -  VERSION
    d  attachments
    d  conf
    d  db
    d  htdocs
    d  log
    d  plugins
    d  templates

With a trac.ini file. Let's check its content::

    >>> f = join(sample_buildout, 'parts', 'trac', 'conf', 'trac.ini')
    >>> from ConfigParser import ConfigParser
    >>> parser = ConfigParser()
    >>> null = parser.read([f])
    >>> parser.get('repositories', 'repo1.type')
    'hg'
    >>> parser.get('repositories', 'repo1.dir')
    '/sample-buildout/var/svn'
    >>> parser.get('project', 'descr')
    'My example project'
    >>> parser.get('project', 'name')
    'My project'
    >>> parser.get('project', 'url')
    ''
    >>> parser.get('components', 'tracext.hg.*')
    'enabled'


Check the milestones::

    >>> from trac.admin.console import TracAdmin
    >>> from trac.ticket.model import Milestone, Component
    >>> location = join(sample_buildout, 'parts', 'trac')
    >>> trac = TracAdmin(location)
    >>> Milestone(trac.env, name='0.1')
    <trac.ticket.model.Milestone object at ...
    >>> Milestone(trac.env, name='Future')
    <trac.ticket.model.Milestone object at ...
    >>> Milestone(trac.env, name='milestone1')
    Traceback (most recent call last):
    ...
    ResourceNotFound: Milestone milestone1 does not exist.


Check the components::

    >>> component = Component(trac.env, name='The application itself')
    >>> component
    <trac.ticket.model.Component object at ...
    >>> component.owner
    u'kevin'
    >>> Component(trac.env, name='component1')
    Traceback (most recent call last):
    ...
    ResourceNotFound: Component component1 does not exist.


Support
=======

- Documentation: http://pypi.python.org/pypi/pbp.recipe.trac

- Bug tracker: http://bitbucket.org/tarek/atomisator/issues

- Source: http://bitbucket.org/tarek/atomisator/src/tip/packages/pbp.recipe.trac/

- Tutorial, example and how-to migrate from a legacy Trac instance:
  http://kevin.deldycke.com/2010/12/automate-trac-instance-deployment-buildout/

- Page about Buildout-based installation on Trac wiki:
  http://trac.edgewall.org/wiki/CookBook/TracBuildout

- pbp.recipe.trac is a sub-project of Atomistor: http://atomisator.ziade.org
