wiki:DevGuide

Version 10 (modified by rjollos, 3 months ago) (diff)

Fixed grammar.

Plugin Development Guide

This document captures some best practices and guidelines for plugin development. It is a community driven document, and everyone is encouraged to contribute to it. If you have questions or comments, please raise them on the Trac-dev MailingList.

License

Plugin authors are encouraged to clearly indicate how the contribution is licensed. This is important for both users and future developers of your plugin. Having a clearly defined license allows someone else to adopt and carry on development of the plugin if you choose to no longer support it. It is also important for users and administrators who need to understand the terms and conditions under which they can use or modify the code.

Trac-Hacks is an open source community driven by voluntary contributions and made successful by collaboration. Therefore we encourage the use of licenses that foster collaboration and minimal restrictions on future use of the code. Trac has adopted the BSD 3-Clause license, and use of the same license in any plugin code is encouraged. One of the many benefits to adopting this license is that any plugin code can potentially be integrated into the Trac core down the road.

The following steps are suggested:

  1. Add the license keyword in setup.py (example).
  2. Add a license header to every Python source file (example).
    # -*- coding: utf-8 -*-
    #
    # Copyright (C) your name here <your email here>
    # All rights reserved.
    #
    # This software is licensed as described in the file COPYING, which
    # you should have received as part of this distribution.
    
  3. Add a license header to every RSS and XHTML Genshi template (example: TBD).
    <!--!
      Copyright (C) your name here <your email here>
      All rights reserved.
    
      This software is licensed as described in the file COPYING, which
      you should have received as part of this distribution.
    -->
    
    The use of the XML comment marker as shown is important so that the text does not get rendered to the output. Make sure not to use the alternate form, which is rendered to the output as a hidden comment: <!-- This is also a comment -->
  4. Add a COPYING file with the license text in the top-level directory of the project (example).
  5. Add an appropriate tag to the wiki page: bsd-license, apache-license, gpl-license, lgpl-license, mit-license. Additional tags can be created for additional or more descriptive license types

Currently it is not recommended to add license text to static resources (i.e. file in htdocs), since doing so will increase the size of the content that is sent to the client. This issue will be addressed in the Trac core when support is added for minimization (trac:#10672).

Metadata for Single-File Plugins

Plugins are typically packaged using setuptools egg format, but Trac also supports single-file plugins. A single-file plugins is a single .py file that is placed in the project or shared plugins directory. While the metadata for a packaged plugin is stored in its setup.py file, the metadata for a single-file plugin can added using file-scope attributes. The supported attributes and their aliases are: author, author_email, home_page (url), license, trac and version (revision).

revision = "$Rev$"
homepage = "http://trac-hacks.org/wiki/MyAmazingMacro"
license = "3-Clause BSD"
author = "Guido van Rossum"
author_email = "trac@python.org"

The attributes should be self-explanatory with the possible exception of the trac attribute. The trac attribute is used to direct bug reports to an issue tracker that differs from homepage. If the plugin is hosted on trac-hacks.org and the homepage attribute is set to point to the project wiki page, the trac attribute will not need to be set.

For files stored in Subversion, Keyword Substitution is supported for the homepage (url) and version (revision) attributes.

homepage = '$URL$'
version = '$Rev$'
url = '$URL$'
revision = '$Rev$'

The file's svn:keywords property must be edited to append Rev and/or URL. Note that the aliases Revision, LastChangedRevision and HeadURL are not supported.

svn propedit svn:keywords MyAmazingMacro.py

Keep in mind that keywords are only expanded when the files are checked-out of version control. If the files are downloaded directly from a Trac repository or the repository is cloned using Git-SVN, then the keywords will not be expanded in the source.

Coding Style

Authors are encouraged to conform to the Trac Style Guide and PEP-0008 style guide.

There are numerous other recommendations, and while some are mainly a matter of personal esthetic and preference, others are suggested for review and adoption:

Example of common style:

not req.authname or req.authname == 'anonymous'

same in 'Yoda condition' style

not req.authname or 'anonymous' == req.authname

Assert Minimum Trac Version Requirement

The most common method employed to specify a minimum required Trac version is to add an installation requirement in setup.py. For example: install_requires = ['Trac >= 0.12']. This causes numerous problems, some of which are documented in #9800, and is not recommended. One of the most negative consequences is that setuptools may download and install a newer version of Trac. The result can be an unintended upgrade of a user's installation (#10607).

A better approach is to place the following in the package __init__.py, modifying min_trac_version as appropriate for your plugin:

import pkg_resources
min_trac_version = '0.12'
pkg_resources.require('Trac >= %s' % min_trac_version)

The check if performed at runtime, so the egg can be built in an environment that does not satisfy the installation requirements. One use-case for this behavior is building the egg on a development computer and uploading it through the plugin admin page. An error such as the following will be seen in the logs if the plugin fails to load due to a failed requirement:

02:39:22 PM Trac[loader] DEBUG: Loading changelog.ChangeLogMacro from /home/user/Workspace/clm/lib/python2.7/site-packages/ChangeLogMacro-0.2-py2.7.egg
02:39:22 PM Trac[loader] ERROR: Skipping "changelog.ChangeLogMacro = changelog.ChangeLogMacro": (version conflict "VersionConflict: (Trac 0.12 (/home/user/Workspace/clm/trac-0.12), Requirement.parse('Trac>=1.0'))")